106:T7e3,Serves the room's git repo, **as of the commit `main` points at** — never the checkout on disk, so a half-written edit or a merge in flight is not something a reader can see, and `.git` is not a path anybody can name because it is not in the tree. `commit` says exactly which snapshot this listing is. `path` is a directory relative to the repo root and defaults to it; `..`, an absolute path, a backslash, a control character, a doubled slash and leading or trailing whitespace are all refused (400) before git is asked anything — the whitespace rule is a refusal rather than a repair, because a filename may legitimately end in a space and trimming the request would answer with a different file. **The server never rewrites a path**, so every `path` in a listing can be handed straight to the content route. Entries come back directories first, then files, each group in code-unit order — byte order rather than the machine's locale, so one room lists identically everywhere. **Membership gates it exactly as reading the room's history does** — a caller who is not on the roster gets the same 404 an unknown room gets, so a room id is never a capability, and an agent that IS a member may read, because a room's files are what its members are working on together. A member of a room that has no files of its own gets 409 `ROOM_HAS_NO_REPO`, and that question is asked strictly AFTER membership so that nobody can learn which rooms are project rooms by probing ids. Each entry carries the last commit that touched it — author, time and subject — from one bounded walk of the room's history, so a directory of five hundred files costs the same handful of git commands as a directory of five; an entry nobody touched inside that window answers `lastCommit: null`, which means "not known here" rather than "never changed". A symlink is listed as a `symlink` and is never followed. Everything here — filenames, commit subjects, author names — is written by the room's members: render it as untrusted text.107:T81b,Writes one file into the room's own copy and commits it, **as one commit authored by the person who saved it**. The file is named in the body rather than the URL, so a save and a read spell a path the same way. **People only**: a member AGENT is refused 403 `PEOPLE_ONLY` — it has a working copy of its own and `merge_to_room_main` to bring work back through, and a second writer in the integration tree is the one-writer rule undone. Membership is still asked first, so a non-member gets the same 404 an unknown room gets. **Optimistic locking is about the FILE**: `baseCommit` is the commit the editor read it at, and the save is refused 409 `FILE_CHANGED` only if THAT PATH changed since — not merely because the room moved on, which it does every time anybody merges. That refusal carries `conflict` — the commit `main` is at now, and who last touched the file — which is what a reload / keep-mine choice is drawn from; sending the conflict's own commit back as `baseCommit` is how a person overwrites deliberately. Saving text that is byte-for-byte what the file already held commits nothing and answers `committed: false`. Refused otherwise with: `ROOM_FILE_PATH_INVALID` (a path that could mean somewhere else, or that names the room's own git directory in any of its spellings), `ROOM_FILE_NOT_READABLE` (a folder, a link, or another repository — a save never writes through a link), `ROOM_FILE_NOT_FOUND` (a folder the room does not have; saving does not make new folders), `ROOM_FILE_NOT_TEXT` (a `NUL` byte, which would make the file unreadable through the read route), `FILE_TOO_LARGE` and `REPO_CAP_EXCEEDED` against the room's own frozen caps, `MAIN_CHECKOUT_DIRTY` while something outside DorkOS has written in the room's copy, and `ROOM_ARCHIVED`. **Two ceilings, two answers**: the request body limit is 1 MB, below the default file cap, so a very large save never reaches the room's own cap at all — it is refused 413 `REQUEST_TOO_LARGE` by the request parser, where a save that fits the request and not the room is refused 409 `FILE_TOO_LARGE`.108:T41c,A room’s own copy has one writer and it is DorkOS, so anything uncommitted in it came from outside — a person with a terminal — and while it is there, every merge and every save in the room refuses `MAIN_CHECKOUT_DIRTY`. This is the way out. `{"action":"commit"}` keeps everything as one commit authored by you; `{"action":"discard","paths":[…]}` throws away exactly the files named, and every one of them has to be a path `GET /repo/status` is reporting as changed right now — anything else is 404, so a screen drawn ten minutes ago cannot delete something that arrived since. Committing keeps work and loses nothing, which is why it needs no list; discarding is the only irreversible act on this surface, which is why it demands one. **Operator-only** (403 `OPERATOR_ONLY`). A room’s copy that is on some other branch is refused rather than fixed — DorkOS does not check out over work it did not put there. `clean` in the answer says whether the room is unstuck: discarding some of the changes and not others leaves it paused, honestly.109:T418,The room’s own copy of the file and the member’s working copy, so the review can be drawn side by side. **Not the ordinary file API**: a member’s working copy lives under the DorkOS data directory, which the raw file surfaces are deliberately confined out of — so this names a room and a DOCUMENT, and the tree and the path both come off that row rather than being chosen by the caller. `base` is the empty string for a file this work ADDS, which is ordinary rather than an error. **People only, unlike every other room read**: this hands back the contents of somebody ELSE’s working copy, which an agent is refused everywhere else, so a member agent is refused 403 `PEOPLE_ONLY` — the same instrument `PUT /:id/files/content` uses. Membership is asked FIRST, so a caller who is not on the roster gets the same 404 an unknown room gets and never learns the room exists. Any member who is a person may read it; whether they may MERGE what they see is a separate question, answered by `POST /:id/repo/merge`, which is the owner’s alone.10a:T556,Snapshot on a cold connect, gap-free replay from `Last-Event-ID`, then live. The same path also answers a WebSocket upgrade, which is what the DorkOS app uses (ADR 260805-041016) — identical contract, each message a JSON text frame, resuming from `?resume=`, with refusals as close code `4000 + status`. Event ids are `---`, the same shape the session stream uses; a cursor from another room, another server process, another seq space, or in the older generation-less format falls back to a cold connect. The `snapshot` frame carries `RoomSnapshot`; every later frame is a `RoomEvent` — a durable `entry`, an ephemeral `signal` that is never replayed, or a `reaction`. A `reaction` frame is durable state and still carries no `id:` line, because the cursor is the highest ENTRY a reader holds and a second number in one header is a cursor clients get wrong: instead each frame carries an entry's WHOLE current reaction set, so one missed frame self-heals on the next. A resume emits one of these for EVERY entry in the trailing window after the replay, empty sets included — that is what corrects a reaction somebody took back while this reader was disconnected, which nothing else on the wire could say. Every entry on every path — the snapshot, the replay, a live `entry` frame — arrives with its own `reactions` attached.10b:T60b,The one write path onto read state, for every kind of thread there is: a room, an agent session, or the inbox. Monotonic — a value at or below the stored one is ignored, so a stale client on a second device cannot un-read a thread for the first one. The response is always the cursor as it now stands, which is the higher of the stored value and the requested one, so a refused write answers with what still holds rather than with an error. **Every write that actually moves the cursor broadcasts `read_cursor` on `GET /api/events`**, carrying the user, the kind, the thread and the new position; a write that changes nothing broadcasts nothing. The cursor written is always the caller's own — there is no way to name a user in this request, and therefore no way to read or move anybody else's read state. **Only people have read state here** — a caller the server resolves as an agent (one presenting a valid `X-DorkOS-Agent`) is refused with 403 `PEOPLE_ONLY`, and one whose token does not verify is refused with 401, because what an agent has been shown is the room-MEMBERSHIP cursor and not this one — advanced by the ambient participation loop as entries are delivered to it, and reachable through no route at all. **A `room` cursor is written through the rooms domain**, so the caller must be able to see the room (404 `ROOM_NOT_FOUND` / `MEMBER_NOT_FOUND` otherwise), and the broadcast carries the unread count the room list redraws from. A `session` or `inbox` cursor names a thread this server cannot check and is stored as given.10c:T45e,One read-only aggregation over the `authors` registry (people) and the mesh cache (agents). It writes nothing and mints nothing: every id it returns already existed, which is why there is no POST here (ADR 260806-222535). Exactly one row carries `isSelf: true` — the operator reading it, under their real name rather than the room-scoped `You` — and `person.email` is carried on that row and no other. `ownerId` is derived at read time: the operator on every locally-registered agent, `null` on a system agent and on every person. `agent.recentlyActive` restates `healthStatus === "active"`, which the mesh defines as "seen within the last hour" — it is not a live-turn signal. Degradation follows ADR-0310, and covers EVERY read rather than just the two registries: `authors`, `agents`, `operator` (the account lookup) and `config` each contribute a `warnings[]` entry on failure while the rest still return, so a roster that cannot say your name still lists your agents and this endpoint has no 500 path through its sources. `warnings` is omitted entirely when every source read cleanly — never sent as `[]`.10d:T5b5,Where a member can be found, for their profile (spec `profile-unification` §3.2). `memberId` is a ROSTER id, which is why this lives under `/api/team` rather than `/api/rooms`: for a person it is their `authors` row id, and for an agent — a system agent included — it is the mesh manifest ULID, whose author row is found by the generation stamp `minted_for_manifest_id`. An agent’s own author id is deliberately NOT accepted; the roster never hands one out. Archived rooms are left out, and rooms come back newest activity first. Each room carries the three fields a renderer needs to name it — `kind`, `slug` and `name` (the title) — rather than a pre-rendered `#general`: a channel reads as its slug and a direct message as its title, and the client owns that rule in one place. `slug` is null on a DM. A member who is in no rooms answers 200 with an empty list — only an id this install has never heard of is a 404, so a client can tell "nobody by that name" from "nowhere yet". A newly registered agent has no author row until it is first in a room, and is answered as the empty list rather than as unknown. **People only.** The path takes any member’s id, so an agent that could call it would read the title of every direct message the operator has — the membership scope the rooms domain imposes, walked around by asking about somebody else. An agent presenting `X-DorkOS-Agent` is refused (403 `PEOPLE_ONLY`), the same way read state is.10e:T684,One ranked read over the derived message index — rooms, Claude Code transcripts, Codex rollouts and OpenCode conversations alike, in a single relevance order, because "where did we talk about X" does not know which one X was said in. A hit is a COORDINATE plus a marked excerpt (source, container, ordinal, role, timestamp), never the message itself: the index holds a copy of the text and none of the access rules, so resolving a hit back to a message stays the owning store's job. Matching is by word STEM, not substring: `dogs` finds "dog", "dogs" and "DOGGED", and `ogs` finds nothing. The index is as fresh as the last five-minute sweep. **Who sees what**: the operator gets every room and every session; anybody else gets only the rooms they are on the roster of, each above the point they joined it, and NO sessions at all — a caller presenting an agent identity, resolved or not, never reaches a transcript. A search scoped to something the caller may not see returns exactly what a search for words nobody ever said returns, so neither a room id nor a query string is a capability. **The calling contract**: at least one WORD of 2 characters, and wait 200 ms after the last keystroke. Ranking cost grows with how many rows MATCH rather than with `limit`, so a one-letter search is the most expensive one there is and the least useful. `limit` is clamped to 50 rather than refused. Degradation follows ADR-0310: a source that could not be fully indexed contributes zero hits and one `warnings[]` entry naming it — never a failed request. `warnings` is always present, `[]` included, and names no container, since a container id is a room or a session id.10f:T437,Writes the name to the two sources the roster actually reads above the author record: the account record (`user.name`), when this install has an account at all, and the stored profile (`config.profile.displayName`), always. It deliberately does NOT write `authors.display_name`: on an install with login off that column is refreshed back to the literal "You" on the next request, and on an install with an account writing it would relabel every message the person has ever posted rather than label them going forward. Only a person may call this; an agent presenting a valid identity token is refused (403), and one whose token this machine cannot verify is refused (401). Because it is the only door that refuses agents, it is also the only one that may record a name as the person’s own: every save stamps `config.profile.displayNameSource` to `{"kind":"operator"}`, INCLUDING a save that does not change the value. That is how somebody dismisses the "Suggested by " note the roster and the account menu draw over a name an agent set through `config_patch` (DOR-1022).110:T60e,One row per agent file, one cell per agent tool the project has turned on, and the projection plan’s own sentence under each — never a paraphrase, so the terminal and the screen say the same thing about the same file. **It writes nothing**: no manifest is scaffolded, nothing is turned on, and no settings store is opened. That is DOR-678’s rule, learned when `dorkos harness sync --check` scaffolded a manifest into whatever folder a person happened to be standing in. **`state` answers for the project as a whole**, and has four values. `ready` — the manifest parsed and everything below is populated. `not-set-up` — there is no `.agents/harness.manifest.json`, answered `200` rather than `404`, because a project with no manifest is a state the app is built to draw and a `404` would say the route is not there. `unreadable` — there is one and it will not parse, with `detail` saying why in words a person can act on. `unavailable` — a build with no harness service at all; it belongs to the in-process (Obsidian) transport and is never produced here. On anything but `ready` every list is empty and every count is zero. **No file bytes**: the response carries artifact names, repo-relative paths and reasons, and a withheld package’s hook commands are deliberately left out of it. `projectPath` must be absolute — a relative one is refused rather than resolved against wherever the server was started — and inside the configured directory boundary or under `{dorkHome}/agents`, the subtree every DorkOS-managed agent lives in.111:T5a2,Writes what is missing and rewrites what is out of date, then answers with the status recomputed after the write — so the caller renders the tree this call left, not the one it found. **It also removes files.** Links whose skill is gone, a generated hooks file nothing projects hooks to any more, the command wrappers of a package that is no longer installed: each is removed only when DorkOS can prove it wrote it, and every path it takes comes back in `swept` — with the sentence saying why it went in `removals`. The exact same list is readable BEFORE the call, as `sweepPreview` and `removals` on `GET /api/harness/status`, and the two are equal rather than one being a sample of the other. One path in the list is not a deletion: `.claude/settings.local.json` keeps every key you own and loses only the hook entries DorkOS added, and its reason says so. **A person, not an agent.** A caller naming itself an agent, or holding an approval token, is refused: this writes into somebody’s project, so it is a decision a person makes. **A package whose hooks nobody has allowed does not hold up the answer.** Its commands are left out, an approval card goes up, and the package is named in `askedAbout`; the status carries the same packages under `pendingApproval`. When somebody allows one, the projection runs again on its own. `projectPath` must be absolute, and inside the configured directory boundary or under `{dorkHome}/agents`.112:T44f,Moves one skill, by name, out of the folder only some agent tools look in and into `.agents/skills` — one `rename(2)`, plus the link Claude Code reads it through when this project has Claude Code turned on. It answers with the status recomputed after the move, inside the same lock the move ran in, so the caller renders the tree this call left. **A refusal is a `200`.** A skill that is not there, one that is already canonical, one whose settings only Claude Code understands, a target that already has something in it: each comes back in `refusals` with one plain sentence saying what to do about it, because a refusal is an answer rather than a failure. **A person, not an agent.** A caller naming itself an agent, or holding an approval token, is refused: this moves a file a person wrote. With `claudeOnly: true` nothing moves — the skill is recorded in the manifest as belonging to Claude Code, with the reason written out in words, and the other tools are told why they do not get it. `projectPath` must be absolute, and inside the configured directory boundary or under `{dorkHome}/agents`.113:T5ea,List the DorkOS capabilities you can invoke by id: the live, versioned catalog of every entry on the capability registry, each with its id, title, description, permission tier (observe/act/destructive), input/output JSON Schema, and the surfaces (MCP tool, CLI verb, HTTP route) it projects onto. Run any of them with `dorkos call [--input '']`. This is NOT the full list of DorkOS tools: the tasks, relay, mesh, binding, trace, extension tools are registered directly on the MCP server, so they appear in your own tool list rather than in this catalog and cannot be reached by `dorkos call`. They carry a permission tier all the same and answer to the same approval gate, so a tool being absent here is not a tool that runs unasked: deleting a schedule and unregistering an agent are destructive and stop for a person. A destructive tool advertises an `approvalToken` argument, which is how you can tell one from its own schema. Call this to find out what is invocable by capability id and at what tier; look at your tool list for the rest. By default a call returns a compact entry per capability (id, title, tier, and a one line summary), bounded to a page, so discovery does not flood your context. Pass `detail:'full'` for the input and output JSON Schema, `domain` to keep one id prefix (for example `domain:'mcp'`), `query` for a case insensitive substring over id, title, and description, and `limit` with `cursor` to page. When a page is capped it says how many were left out and how to narrow.f0:["$","$Lf8",null,{"toc":[],"full":true,"children":[["$","script",null,{"type":"application/ld+json","dangerouslySetInnerHTML":{"__html":"{\"@context\":\"https://schema.org\",\"@type\":\"TechArticle\",\"headline\":\"Read requester-safe status for one program review\",\"author\":{\"@type\":\"Organization\",\"name\":\"DorkOS\",\"url\":\"https://dorkos.ai\"},\"publisher\":{\"@type\":\"Organization\",\"name\":\"DorkOS\",\"url\":\"https://dorkos.ai\"},\"url\":\"https://dorkos.ai/docs/api/api/connectors/program/reviews/reviewrequestid/get\",\"mainEntityOfPage\":{\"@type\":\"WebPage\",\"@id\":\"https://dorkos.ai/docs/api/api/connectors/program/reviews/reviewrequestid/get\"}}"}}],["$","script",null,{"type":"application/ld+json","dangerouslySetInnerHTML":{"__html":"$f9"}}],["$","$Lfa",null,{"children":"Read requester-safe status for one program review"}],["$","$Lfb",null,{"children":"$undefined"}],false,["$","$Lfc",null,{"children":["$undefined",["$","$Lfd",null,{"document":"../../docs/api/openapi.json","operations":[{"path":"/api/connectors/program/reviews/{reviewRequestId}","method":"get"}],"showDescription":true,"preloaded":{"docs":{"../../docs/api/openapi.json":{"openapi":"3.2.0","info":{"title":"DorkOS API","version":"0.2.0","description":"REST/SSE API for Claude Code sessions, built with the Claude Agent SDK."},"servers":[{"url":"http://localhost:4242"}],"components":{"schemas":{"RelayFlowDirection":{"type":"string","enum":["inbound","outbound"]},"RelayFlowEvent":{"type":"object","properties":{"bindingId":{"type":"string"},"adapterId":{"type":"string"},"agentId":{"type":"string"},"direction":{"$ref":"#/components/schemas/RelayFlowDirection"},"at":{"type":"string","format":"date-time"}},"required":["bindingId","adapterId","agentId","direction","at"]},"HarnessStatusResponse":{"type":"object","properties":{"projectPath":{"type":"string"},"state":{"type":"string","enum":["ready","not-set-up","unreadable","unavailable"]},"detail":{"type":"string"},"computedAt":{"type":"string"},"enabled":{"type":"array","items":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]}},"notEnabled":{"type":"array","items":{"type":"object","properties":{"harness":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]},"why":{"type":"string","enum":["footprint","dorkos-runtime"]},"signal":{"type":"string"}},"required":["harness","why"]}},"clean":{"type":"boolean"},"counts":{"type":"object","properties":{"skills":{"type":"integer","minimum":0},"globalSkills":{"type":"integer","minimum":0},"drifted":{"type":"integer","minimum":0},"conflicts":{"type":"integer","minimum":0},"orphans":{"type":"integer","minimum":0},"adoptable":{"type":"integer","minimum":0},"pendingApproval":{"type":"integer","minimum":0}},"required":["skills","globalSkills","drifted","conflicts","orphans","adoptable","pendingApproval"]},"sweepPreview":{"type":"array","items":{"type":"string"}},"removals":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"rows":{"type":"array","items":{"type":"object","properties":{"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"provenance":{"type":"string","enum":["authored","installed","harness-native"]},"scope":{"type":"string","enum":["project","global"],"default":"project"},"name":{"type":"string"},"source":{"type":"string"},"adoptable":{"type":"boolean"},"cells":{"type":"object","properties":{"claude-code":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"codex":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"cursor":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"gemini":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"copilot":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"opencode":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]}}}},"required":["artifact","provenance","name","adoptable","cells"]}},"projectLevel":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["drop","warning","write","notice"]},"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"name":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"reason":{"type":"string"}},"required":["kind","artifact","name","reason"]}},"pendingApproval":{"type":"array","items":{"type":"object","properties":{"packageName":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"commandCount":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["unasked","refused","unreadable-config"]},"detail":{"type":"string"}},"required":["packageName","events","commandCount","reason"]}},"claudeOnly":{"type":"object","properties":{"root":{"type":"string"},"readAt":{"type":"string"},"unreadable":{"type":"string"},"mayBeOverridden":{"type":"boolean"},"plugins":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"marketplace":{"type":"string"},"repo":{"type":"string"},"settingsScope":{"type":"string","enum":["user","project"]},"offer":{"type":"string","enum":["install","add-source-then-install","unknown-source","no-package","sources-unreadable"]},"sourceUrl":{"type":"string"}},"required":["name","marketplace","settingsScope","offer"]}},"personalHookCommands":{"type":"integer","minimum":0},"unreadableParts":{"type":"array","items":{"type":"string","enum":["extraKnownMarketplaces","hooks"]}},"skippedEntries":{"type":"integer","minimum":0},"sourcesUnreadable":{"type":"string"}},"required":["root","readAt","mayBeOverridden","plugins","personalHookCommands","unreadableParts"]}},"required":["projectPath","state","computedAt","enabled","notEnabled","clean","counts","sweepPreview","removals","rows","projectLevel","pendingApproval"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"uptime":{"type":"number"},"tunnel":{"$ref":"#/components/schemas/TunnelStatus"}},"required":["status","version","uptime"]},"TunnelStatus":{"type":"object","properties":{"enabled":{"type":"boolean"},"connected":{"type":"boolean"},"isRunning":{"type":"boolean"},"url":{"type":["string","null"]},"port":{"type":["integer","null"]},"startedAt":{"type":["string","null"]},"authEnabled":{"type":"boolean"},"tokenConfigured":{"type":"boolean"},"domain":{"type":["string","null"]}},"required":["enabled","connected","isRunning","url","port","startedAt","authEnabled","tokenConfigured","domain"]},"SessionListResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SessionListWarning"}}},"required":["sessions"]},"Session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastMessagePreview":{"type":"string"},"permissionMode":{"$ref":"#/components/schemas/PermissionModeId"},"runtime":{"type":"string"},"model":{"type":"string"},"effort":{"$ref":"#/components/schemas/EffortLevel"},"fastMode":{"type":"boolean"},"contextTokens":{"type":"integer"},"lastAutoCompactAt":{"type":"string","format":"date-time"},"origin":{"$ref":"#/components/schemas/SessionOrigin"},"originLabel":{"type":"string"},"originRoomId":{"type":"string"},"account":{"type":"string"},"userLastMessageAt":{"type":"string","format":"date-time"},"cwd":{"type":"string"}},"required":["id","title","createdAt","updatedAt","permissionMode","runtime"]},"PermissionModeId":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"},"EffortLevel":{"type":"string","enum":["none","minimal","low","medium","high","max","xhigh"]},"SessionOrigin":{"type":"string","enum":["user","agent","channel","room","task","external"]},"SessionListWarning":{"type":"object","properties":{"runtime":{"type":"string"},"message":{"type":"string"},"account":{"type":"string"}},"required":["runtime","message"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"]},"PendingInteractionsResponse":{"type":"object","properties":{"interactions":{"type":"array","items":{"$ref":"#/components/schemas/InteractionPendingEvent"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["interactions"]},"InteractionPendingEvent":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1},"cwd":{"type":"string","minLength":1},"interaction":{"$ref":"#/components/schemas/PendingInteractionDTO"},"roomId":{"type":"string","minLength":1},"roomAuthorId":{"type":"string","minLength":1}},"required":["sessionId","cwd","interaction"]},"PendingInteractionDTO":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["approval"]},"id":{"type":"string"},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"parked":{"type":"boolean"},"toolName":{"type":"string"},"input":{"type":"string"},"title":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"blockedPath":{"type":"string"},"decisionReason":{"type":"string"},"hasSuggestions":{"type":"boolean"},"alwaysAllowScope":{"$ref":"#/components/schemas/AlwaysAllowScope"}},"required":["type","id","startedAt","remainingMs","toolName","input","hasSuggestions"]},{"type":"object","properties":{"type":{"type":"string","enum":["question"]},"id":{"type":"string"},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"parked":{"type":"boolean"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionItem"}}},"required":["type","id","startedAt","remainingMs","questions"]},{"type":"object","properties":{"type":{"type":"string","enum":["elicitation"]},"id":{"type":"string"},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"parked":{"type":"boolean"},"serverName":{"type":"string"},"message":{"type":"string"},"mode":{"$ref":"#/components/schemas/ElicitationMode"},"url":{"type":"string"},"elicitationId":{"type":"string"},"requestedSchema":{"type":"object","additionalProperties":{}}},"required":["type","id","startedAt","remainingMs","serverName","message"]}]},"AlwaysAllowScope":{"type":"string","enum":["session","project","user"]},"QuestionItem":{"type":"object","properties":{"header":{"type":"string","default":""},"question":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/QuestionOption"}},"multiSelect":{"type":"boolean","default":false}},"required":["question","options"]},"QuestionOption":{"type":"object","properties":{"label":{"type":"string"},"description":{"type":"string"}},"required":["label"]},"ElicitationMode":{"type":"string","enum":["form","url"]},"RecentSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"agentActivity":{"type":"object","additionalProperties":{"type":"string"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SessionListWarning"}}},"required":["sessions","agentActivity"]},"SessionDailyCountsResponse":{"type":"object","properties":{"days":{"type":"integer"},"dailyCounts":{"type":"array","items":{"type":"integer"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SessionListWarning"}}},"required":["days","dailyCounts"]},"HistoryMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"toolCalls":{"type":"array","items":{"$ref":"#/components/schemas/HistoryToolCall"}},"parts":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextPart"},{"$ref":"#/components/schemas/ImagePart"},{"$ref":"#/components/schemas/ToolCallPart"},{"$ref":"#/components/schemas/BackgroundTaskPart"},{"$ref":"#/components/schemas/ThinkingPart"},{"$ref":"#/components/schemas/ErrorPart"},{"$ref":"#/components/schemas/ElicitationPart"},{"$ref":"#/components/schemas/CapabilityApprovalPart"},{"$ref":"#/components/schemas/McpSigninPart"},{"$ref":"#/components/schemas/MemoryRecallPart"},{"$ref":"#/components/schemas/PermissionDeniedPart"},{"$ref":"#/components/schemas/CompactBoundaryPart"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TextPart","image":"#/components/schemas/ImagePart","tool_call":"#/components/schemas/ToolCallPart","background_task":"#/components/schemas/BackgroundTaskPart","thinking":"#/components/schemas/ThinkingPart","error":"#/components/schemas/ErrorPart","elicitation":"#/components/schemas/ElicitationPart","capability_approval":"#/components/schemas/CapabilityApprovalPart","mcp_signin":"#/components/schemas/McpSigninPart","memory_recall":"#/components/schemas/MemoryRecallPart","permission_denied":"#/components/schemas/PermissionDeniedPart","compact_boundary":"#/components/schemas/CompactBoundaryPart"}}}},"timestamp":{"type":"string"},"messageType":{"$ref":"#/components/schemas/MessageType"},"compactMetadata":{"$ref":"#/components/schemas/CompactMetadata"},"commandName":{"type":"string"},"commandArgs":{"type":"string"}},"required":["id","role","content"]},"HistoryToolCall":{"type":"object","properties":{"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"progressOutput":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionItem"}},"answers":{"type":"object","additionalProperties":{"type":"string"}},"questionOutcome":{"type":"string","enum":["answered","expired","denied","cancelled","errored","unresolved"]},"approvalOutcome":{"type":"string","enum":["allowed","denied","expired"]},"approvalResolvedAt":{"type":"number"},"approvalReasonGiven":{"type":"boolean"},"approvalStartedAt":{"type":"number"}},"required":["toolCallId","toolName","status"]},"TextPart":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},"ImagePart":{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"attachmentId":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"mediaType":{"type":"string","minLength":1},"size":{"type":"integer","minimum":0},"alt":{"type":"string"}},"required":["type","attachmentId","url","mediaType","size"]},"ToolCallPart":{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"progressOutput":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"interactiveType":{"type":"string","enum":["approval","question"]},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionItem"}},"answers":{"type":"object","additionalProperties":{"type":"string"}},"questionOutcome":{"type":"string","enum":["answered","expired","denied","cancelled","errored","unresolved"]},"timeoutMs":{"type":"number","description":"Approval timeout duration in milliseconds"},"approvalStartedAt":{"type":"number"},"approvalRemainingMs":{"type":"number"},"approvalParked":{"type":"boolean"},"approvalTitle":{"type":"string","description":"Full permission prompt sentence from SDK"},"approvalDisplayName":{"type":"string","description":"Short noun phrase for the tool action"},"approvalDescription":{"type":"string","description":"Human-readable subtitle from SDK"},"approvalBlockedPath":{"type":"string","description":"File path that triggered the permission"},"approvalDecisionReason":{"type":"string","description":"Why this permission request was triggered"},"approvalHasSuggestions":{"type":"boolean","description":"Whether \"Always Allow\" is available"},"approvalAlwaysAllowScope":{"allOf":[{"$ref":"#/components/schemas/AlwaysAllowScope"},{"description":"Scope an accepted \"Always Allow\" grants — session, project, or the operator's global settings"}]},"approvalOutcome":{"type":"string","enum":["allowed","denied","expired"],"description":"How an approval was answered — drives the transcript receipt line"},"approvalReasonGiven":{"type":"boolean"},"approvalResolvedAt":{"type":"number"},"hooks":{"type":"array","items":{"type":"object","properties":{"hookId":{"type":"string"},"hookName":{"type":"string"},"hookEvent":{"type":"string"},"status":{"type":"string","enum":["running","success","error","cancelled"]},"stdout":{"type":"string"},"stderr":{"type":"string"},"exitCode":{"type":"number"}},"required":["hookId","hookName","hookEvent","status","stdout","stderr"]}},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"ui":{"$ref":"#/components/schemas/McpAppRef"}},"required":["type","toolCallId","toolName","status"]},"McpAppRef":{"type":"object","properties":{"resourceUri":{"type":"string"},"preferredDisplayMode":{"type":"string","enum":["inline","fullscreen","pip"]}},"required":["resourceUri"]},"BackgroundTaskPart":{"type":"object","properties":{"type":{"type":"string","enum":["background_task"]},"taskId":{"type":"string"},"taskType":{"$ref":"#/components/schemas/BackgroundTaskType"},"status":{"$ref":"#/components/schemas/BackgroundTaskStatus"},"startedAt":{"type":"number"},"description":{"type":"string"},"toolUses":{"type":"integer"},"lastToolName":{"type":"string"},"summary":{"type":"string"},"toolUseId":{"type":"string"},"subagentText":{"type":"string"},"command":{"type":"string"},"durationMs":{"type":"integer"},"ambient":{"type":"boolean"}},"required":["type","taskId","taskType","status","startedAt"]},"BackgroundTaskType":{"type":"string","enum":["agent","bash"]},"BackgroundTaskStatus":{"type":"string","enum":["running","complete","error","stopped","untracked"]},"ThinkingPart":{"type":"object","properties":{"type":{"type":"string","enum":["thinking"]},"text":{"type":"string"},"isStreaming":{"type":"boolean"},"elapsedMs":{"type":"integer"}},"required":["type","text"]},"ErrorPart":{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"message":{"type":"string"},"category":{"$ref":"#/components/schemas/ErrorCategory"},"details":{"type":"string"},"code":{"type":"string"}},"required":["type","message"]},"ErrorCategory":{"type":"string","enum":["max_turns","execution_error","budget_exceeded","output_format_error","auth_error","model_unavailable","runtime_update_required"]},"ElicitationPart":{"type":"object","properties":{"type":{"type":"string","enum":["elicitation"]},"interactionId":{"type":"string"},"serverName":{"type":"string"},"message":{"type":"string"},"mode":{"$ref":"#/components/schemas/ElicitationMode"},"url":{"type":"string"},"elicitationId":{"type":"string"},"requestedSchema":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["pending","submitted","complete"]},"action":{"$ref":"#/components/schemas/ElicitationAction"},"content":{"type":"object","additionalProperties":{}},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"}},"required":["type","interactionId","serverName","message","status"]},"ElicitationAction":{"type":"string","enum":["accept","decline","cancel"]},"CapabilityApprovalPart":{"type":"object","properties":{"type":{"type":"string","enum":["capability_approval"]},"approval":{"$ref":"#/components/schemas/PendingApproval"},"outcome":{"type":"string","enum":["timeout"]}},"required":["type","approval"]},"PendingApproval":{"type":"object","properties":{"approvalId":{"type":"string"},"capabilityId":{"type":"string"},"capabilityTitle":{"type":"string"},"tier":{"type":"string","enum":["observe","act","destructive"]},"summary":{"type":"string","maxLength":500},"requestedBy":{"type":"string"},"hasAgentPath":{"type":"boolean"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"detail":{"type":"string","maxLength":4000},"subject":{"$ref":"#/components/schemas/ApprovalSubject"},"origin":{"type":"string","enum":["session","external-mcp"]},"otherArguments":{"type":"string","maxLength":500}},"required":["approvalId","capabilityId","capabilityTitle","tier","summary","hasAgentPath","requestedAt","expiresAt"]},"ApprovalSubject":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task"]},"label":{"type":"string","maxLength":60},"id":{"type":"string","maxLength":60}},"required":["kind","label","id"]},"McpSigninPart":{"type":"object","properties":{"type":{"type":"string","enum":["mcp_signin"]},"serverName":{"type":"string"},"agentId":{"type":"string"},"flowId":{"type":"string"},"authorizeUrl":{"type":"string"},"disclosure":{"type":"string"},"outcome":{"type":"string","enum":["connected","failed"]},"toolCount":{"type":"integer","minimum":0}},"required":["type","serverName","agentId","flowId","authorizeUrl","disclosure"]},"MemoryRecallPart":{"type":"object","properties":{"type":{"type":"string","enum":["memory_recall"]},"mode":{"type":"string","enum":["select","synthesize"]},"memories":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"scope":{"type":"string","enum":["personal","team"]},"content":{"type":"string"}},"required":["path","scope"]}},"isStreaming":{"type":"boolean"}},"required":["type","mode","memories"]},"PermissionDeniedPart":{"type":"object","properties":{"type":{"type":"string","enum":["permission_denied"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"reasonType":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"agentId":{"type":"string"}},"required":["type","toolCallId","toolName","message"]},"CompactBoundaryPart":{"type":"object","properties":{"type":{"type":"string","enum":["compact_boundary"]},"trigger":{"type":"string","enum":["manual","auto"]},"preTokens":{"type":"integer"},"postTokens":{"type":"integer"},"durationMs":{"type":"integer"},"failed":{"type":"boolean"},"error":{"type":"string"}},"required":["type"]},"MessageType":{"type":"string","enum":["command","compaction","local_command_output"]},"CompactMetadata":{"type":"object","properties":{"trigger":{"type":"string","enum":["manual","auto"]},"preTokens":{"type":"integer"},"postTokens":{"type":"integer"},"durationMs":{"type":"integer"}}},"SessionSnapshot":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/HistoryMessage"}},"inProgressTurn":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SessionEvent"}},"status":{"$ref":"#/components/schemas/SessionStatus"},"pendingInteractions":{"type":"array","items":{"$ref":"#/components/schemas/PendingInteractionDTO"}},"queuedMessages":{"type":"array","items":{"$ref":"#/components/schemas/QueuedMessage"}},"canvas":{"type":"array","items":{"$ref":"#/components/schemas/CanvasDocument"}},"cursor":{"type":"integer","minimum":0}},"required":["messages","inProgressTurn","status","pendingInteractions","queuedMessages","canvas","cursor"]},"SessionEvent":{"oneOf":[{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["text_delta"]},"text":{"type":"string"}},"required":["seq","type","text"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["thinking_delta"]},"text":{"type":"string"}},"required":["seq","type","text"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_call"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"ui":{"$ref":"#/components/schemas/McpAppRef"}},"required":["seq","type","toolCallId","toolName","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_result"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"ui":{"$ref":"#/components/schemas/McpAppRef"}},"required":["seq","type","toolCallId","toolName","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_progress"]},"toolCallId":{"type":"string"},"content":{"type":"string"}},"required":["seq","type","toolCallId","content"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["approval_required"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"title":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"blockedPath":{"type":"string"},"decisionReason":{"type":"string"},"hasSuggestions":{"type":"boolean"},"alwaysAllowScope":{"$ref":"#/components/schemas/AlwaysAllowScope"}},"required":["seq","type","startedAt","remainingMs","id","toolName","input","hasSuggestions"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["question_prompt"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionItem"}}},"required":["seq","type","startedAt","remainingMs","id","questions"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["elicitation_prompt"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"serverName":{"type":"string"},"message":{"type":"string"},"mode":{"$ref":"#/components/schemas/ElicitationMode"},"url":{"type":"string"},"elicitationId":{"type":"string"},"requestedSchema":{"type":"object","additionalProperties":{}}},"required":["seq","type","startedAt","remainingMs","id","serverName","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["status_change"]},"status":{"type":"object","properties":{"contextUsage":{"type":["object","null"],"properties":{"totalTokens":{"type":"integer"},"maxTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheCreationTokens":{"type":"integer"}}},"cost":{"type":["number","null"]},"usage":{"$ref":"#/components/schemas/UsageStatus"},"cacheStats":{"$ref":"#/components/schemas/SessionCacheStats"},"model":{"type":["string","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionModeId"},"todoCounts":{"$ref":"#/components/schemas/SessionTodoCounts"},"runningSubagentCount":{"type":"integer","default":0},"lifecycle":{"$ref":"#/components/schemas/SessionLifecycle"},"lastError":{"$ref":"#/components/schemas/ErrorEvent"},"steerable":{"type":"boolean"}}}},"required":["seq","type","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["todo_update"]},"action":{"type":"string","enum":["create","update","snapshot","id_assigned","remove"]},"task":{"$ref":"#/components/schemas/TaskItem"},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/TaskItem"}},"previousId":{"type":"string"}},"required":["seq","type","action","task"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["subagent_update"]},"taskId":{"type":"string"},"status":{"$ref":"#/components/schemas/BackgroundTaskStatus"},"description":{"type":"string"},"toolUses":{"type":"integer"},"lastToolName":{"type":"string"},"summary":{"type":"string"},"ambient":{"type":"boolean"}},"required":["seq","type","taskId","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["hook_update"]},"hookId":{"type":"string"},"status":{"type":"string","enum":["running","success","error","cancelled"]},"hookName":{"type":"string"},"hookEvent":{"type":"string"},"toolCallId":{"type":["string","null"]},"stdout":{"type":"string"},"stderr":{"type":"string"},"exitCode":{"type":"number"}},"required":["seq","type","hookId","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["memory_recall"]},"mode":{"type":"string","enum":["select","synthesize"]},"memories":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"scope":{"type":"string","enum":["personal","team"]},"content":{"type":"string"}},"required":["path","scope"]}}},"required":["seq","type","mode","memories"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["image_attachment"]},"attachmentId":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"mediaType":{"type":"string","minLength":1},"size":{"type":"integer","minimum":0},"alt":{"type":"string"}},"required":["seq","type","attachmentId","url","mediaType","size"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["compact_boundary"]},"trigger":{"type":"string","enum":["manual","auto"]},"preTokens":{"type":"integer"},"postTokens":{"type":"integer"},"durationMs":{"type":"integer"}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["permission_denied"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"reasonType":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"agentId":{"type":"string"}},"required":["seq","type","toolCallId","toolName","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["system_status"]},"message":{"type":"string"},"status":{"type":"string"}},"required":["seq","type","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["operation_progress"]},"operation":{"$ref":"#/components/schemas/OperationKind"},"state":{"$ref":"#/components/schemas/OperationState"},"determinate":{"type":"boolean"},"percent":{"type":"number","minimum":0,"maximum":100},"message":{"type":"string"},"error":{"type":"string"}},"required":["seq","type","operation","state","determinate"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["error"]},"message":{"type":"string"},"code":{"type":"string"},"category":{"$ref":"#/components/schemas/ErrorCategory"},"details":{"type":"string"}},"required":["seq","type","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["interaction_resolved"]},"id":{"type":"string"},"resolution":{"type":"string","enum":["approved","denied","answered","expired","cancelled"]},"kind":{"type":"string","enum":["approval","question","elicitation"]},"at":{"type":"number"},"startedAt":{"type":"number"},"reasonGiven":{"type":"boolean"},"resolvedBy":{"type":"string"}},"required":["seq","type","id"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["capability_approval_required"]},"startedAt":{"type":"number"},"capMs":{"type":"number"},"approval":{"$ref":"#/components/schemas/PendingApproval"}},"required":["seq","type","startedAt","capMs","approval"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["capability_approval_resolved"]},"approvalId":{"type":"string"},"outcome":{"type":"string","enum":["granted","denied","expired","timeout"]}},"required":["seq","type","approvalId","outcome"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["mcp_signin_required"]},"serverName":{"type":"string"},"agentId":{"type":"string"},"flowId":{"type":"string"},"authorizeUrl":{"type":"string"},"disclosure":{"type":"string"}},"required":["seq","type","serverName","agentId","flowId","authorizeUrl","disclosure"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["mcp_signin_resolved"]},"flowId":{"type":"string"},"outcome":{"type":"string","enum":["connected","failed"]},"toolCount":{"type":"integer","minimum":0}},"required":["seq","type","flowId","outcome"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_start"]},"userMessage":{"type":"string"},"origin":{"type":"string","enum":["user","runtime"]}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_end"]},"terminalReason":{"$ref":"#/components/schemas/TerminalReason"},"stopWasRequested":{"type":"boolean"}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_input"]},"content":{"type":"string"},"disposition":{"type":"string","enum":["steer"]},"messageId":{"type":"string"}},"required":["seq","type","content","disposition","messageId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["ui_command"]},"command":{"$ref":"#/components/schemas/UiCommand"},"applied":{"type":"object","properties":{"documentId":{"type":"string","minLength":1},"rev":{"type":"integer","minimum":0}},"required":["documentId","rev"]}},"required":["seq","type","command"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["canvas"]},"documentId":{"type":"string","minLength":1},"document":{"$ref":"#/components/schemas/CanvasDocument"},"closed":{"type":"boolean"},"change":{"type":"string","enum":["opened","updated","activated","pinned"]}},"required":["seq","type","documentId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_capture_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"}},"required":["seq","type","requestId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_action_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"},"command":{"$ref":"#/components/schemas/BrowserActCommand"},"capture":{"type":"boolean"}},"required":["seq","type","requestId","targetClientId","documentId","command"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_recording_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"},"action":{"type":"string","enum":["start","stop"]},"recordingId":{"type":"string"},"bounds":{"type":"object","properties":{"longEdgePx":{"type":"integer","exclusiveMinimum":0},"frameMs":{"type":"integer","exclusiveMinimum":0},"maxBytes":{"type":"integer","exclusiveMinimum":0}},"required":["longEdgePx","frameMs","maxBytes"]}},"required":["seq","type","requestId","targetClientId","documentId","action","recordingId","bounds"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["queue_update"]},"queue":{"type":"array","items":{"$ref":"#/components/schemas/QueuedMessage"}},"outcome":{"$ref":"#/components/schemas/MessageDeliveryOutcome"}},"required":["seq","type","queue"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["context_staged"]},"content":{"type":"string"},"messageId":{"type":"string"}},"required":["seq","type","content","messageId"]}]},"UsageStatus":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["subscription","pay-as-you-go"]},"utilization":{"type":"number","minimum":0},"windowLabel":{"type":"string"},"resetsAt":{"type":"string"},"costUsd":{"type":"number","minimum":0},"costBasis":{"type":"string","enum":["list","managed","unknown"]},"state":{"$ref":"#/components/schemas/UsageState"},"detail":{"type":"string"}},"default":null,"required":["kind"]},"UsageState":{"type":"string","enum":["ok","warning","exhausted"]},"SessionCacheStats":{"type":["object","null"],"properties":{"cacheReadTokens":{"type":"integer"},"cacheCreationTokens":{"type":"integer"}},"required":["cacheReadTokens","cacheCreationTokens"]},"SessionTodoCounts":{"type":["object","null"],"properties":{"total":{"type":"integer"},"completed":{"type":"integer"},"inProgress":{"type":"integer"}},"required":["total","completed","inProgress"]},"SessionLifecycle":{"type":"string","enum":["idle","streaming","blocked","error","interrupted"]},"ErrorEvent":{"type":["object","null"],"properties":{"message":{"type":"string"},"code":{"type":"string"},"category":{"$ref":"#/components/schemas/ErrorCategory"},"details":{"type":"string"}},"default":null,"required":["message"]},"TaskItem":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"description":{"type":"string"},"activeForm":{"type":"string"},"status":{"$ref":"#/components/schemas/SessionTaskStatus"},"blockedBy":{"type":"array","items":{"type":"string"}},"blocks":{"type":"array","items":{"type":"string"}},"owner":{"type":"string"}},"required":["id","subject","status"]},"SessionTaskStatus":{"type":"string","enum":["pending","in_progress","completed"]},"OperationKind":{"type":"string","enum":["compaction"]},"OperationState":{"type":"string","enum":["started","done","failed"]},"TerminalReason":{"anyOf":[{"type":"string","enum":["completed","aborted_tools","aborted_streaming","max_turns","blocking_limit","rapid_refill_breaker","prompt_too_long","image_error","model_error","stop_hook_prevented","hook_stopped","tool_deferred"]},{"type":"string"}]},"UiCommand":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["open_panel"]},"panel":{"$ref":"#/components/schemas/UiPanelId"}},"required":["action","panel"]},{"type":"object","properties":{"action":{"type":"string","enum":["close_panel"]},"panel":{"$ref":"#/components/schemas/UiPanelId"}},"required":["action","panel"]},{"type":"object","properties":{"action":{"type":"string","enum":["toggle_panel"]},"panel":{"$ref":"#/components/schemas/UiPanelId"}},"required":["action","panel"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_sidebar"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["close_sidebar"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["switch_sidebar_tab"]},"tab":{"$ref":"#/components/schemas/UiSidebarTab"}},"required":["action","tab"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_canvas"]},"content":{"$ref":"#/components/schemas/UiCanvasContent"},"preferredWidth":{"type":"number","minimum":20,"maximum":80},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["update_canvas"]},"content":{"$ref":"#/components/schemas/UiCanvasContent"},"documentId":{"type":"string"},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action","content"]},{"type":"object","properties":{"action":{"type":"string","enum":["close_canvas"]},"documentId":{"type":"string"},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_pip"]},"title":{"type":"string"}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["close_pip"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_file"]},"sourcePath":{"type":"string","minLength":1},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action","sourcePath"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_diff"]},"sourcePath":{"type":"string","minLength":1},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action","sourcePath"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_terminal"]},"cwd":{"type":"string"}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["browser_navigate"]},"url":{"type":"string","minLength":1},"target":{"$ref":"#/components/schemas/UiCommandTarget"}},"required":["action","url"]},{"type":"object","properties":{"action":{"type":"string","enum":["show_toast"]},"message":{"type":"string","maxLength":500},"level":{"$ref":"#/components/schemas/UiToastLevel"},"description":{"type":"string","maxLength":1000}},"required":["action","message"]},{"type":"object","properties":{"action":{"type":"string","enum":["set_theme"]},"theme":{"type":"string","enum":["light","dark"]}},"required":["action","theme"]},{"type":"object","properties":{"action":{"type":"string","enum":["scroll_to_message"]},"messageId":{"type":"string"}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["switch_agent"]},"cwd":{"type":"string"}},"required":["action","cwd"]},{"type":"object","properties":{"action":{"type":"string","enum":["apply_layout"]},"shape":{"type":"string","minLength":1}},"required":["action","shape"]},{"type":"object","properties":{"action":{"type":"string","enum":["open_command_palette"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["celebrate"]},"kind":{"$ref":"#/components/schemas/CelebrationKind"},"emoji":{"type":"string","minLength":1,"maxLength":8}},"required":["action"]}]},"UiPanelId":{"type":"string","enum":["settings","tasks","relay","picker"]},"UiSidebarTab":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$","description":"Sidebar tab id, e.g. a built-in ('overview', 'sessions', 'schedules', 'connections'). The sidebar tab strip exists only in the embedded (Obsidian) app; in the web app there is no strip, so switching a sidebar tab is a no-op there."},"UiCanvasContent":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"},"title":{"type":"string"}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown"]},"content":{"type":"string"},"title":{"type":"string"},"sourcePath":{"type":"string"}},"required":["type","content"]},{"type":"object","properties":{"type":{"type":"string","enum":["json"]},"data":{},"title":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"src":{"type":"string","minLength":1},"title":{"type":"string"},"alt":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"src":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["widget"]},"definition":{"type":"object"},"title":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["mcp_app"]},"serverName":{"type":"string"},"uri":{"type":"string"},"title":{"type":"string"}},"required":["type","serverName","uri"]},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"sourcePath":{"type":"string"},"language":{"type":"string"},"readOnly":{"type":"boolean"},"title":{"type":"string"}},"required":["type","sourcePath"]},{"type":"object","properties":{"type":{"type":"string","enum":["model3d"]},"src":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["audio"]},"src":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["video"]},"src":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["csv"]},"src":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","src"]},{"type":"object","properties":{"type":{"type":"string","enum":["browser"]},"url":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["diff"]},"sourcePath":{"type":"string","minLength":1},"mediaKind":{"type":"string","enum":["text","image"]},"title":{"type":"string"}},"required":["type","sourcePath"]}]},"UiCommandTarget":{"type":"object","properties":{"roomId":{"type":"string","minLength":1,"description":"The room id to put this on. You must be a member of it."}},"required":["roomId"]},"UiToastLevel":{"type":"string","enum":["success","error","info","warning"],"default":"info"},"CelebrationKind":{"type":"string","enum":["burst","fireworks","cannons","emoji","rain","stars"]},"CanvasDocument":{"type":"object","properties":{"id":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"roomId":{"type":["string","null"],"minLength":1},"content":{"$ref":"#/components/schemas/UiCanvasContent"},"title":{"type":"string"},"contentType":{"type":"string","minLength":1},"authorId":{"type":"string","minLength":1},"pinned":{"type":"boolean"},"rev":{"type":"integer","minimum":0},"lastTouchedBy":{"type":"string","minLength":1},"lastTouchedAt":{"type":"string","minLength":1},"editingBy":{"type":"string","minLength":1},"sourceLabel":{"type":"string"},"treeKind":{"type":"string","enum":["room-main","worktree","agent-cwd"]},"aheadOfMain":{"type":["integer","null"],"minimum":0},"openedAt":{"type":"string","minLength":1},"lastActiveAt":{"type":"string","minLength":1},"threadRootEntryId":{"type":"string","minLength":1}},"required":["id","scope","roomId","content","title","contentType","authorId","pinned","rev","lastTouchedBy","lastTouchedAt","openedAt","lastActiveAt"]},"BrowserActCommand":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["click"]},"target":{"$ref":"#/components/schemas/BrowserTarget"}},"required":["action","target"]},{"type":"object","properties":{"action":{"type":"string","enum":["type"]},"target":{"$ref":"#/components/schemas/BrowserTarget"},"text":{"type":"string","maxLength":10000},"clear":{"type":"boolean"},"submit":{"type":"boolean"}},"required":["action","text"]},{"type":"object","properties":{"action":{"type":"string","enum":["press"]},"key":{"type":"string","maxLength":64}},"required":["action","key"]},{"type":"object","properties":{"action":{"type":"string","enum":["scroll"]},"target":{"$ref":"#/components/schemas/BrowserTarget"},"by":{"type":"number"},"to":{"type":"string","enum":["top","bottom"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["wait_for"]},"text":{"type":"string","maxLength":512},"selector":{"type":"string","maxLength":512},"gone":{"type":"boolean"},"fetchIdle":{"type":"boolean"},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["action","timeoutMs"]},{"type":"object","properties":{"action":{"type":"string","enum":["read_page"]},"selector":{"type":"string","maxLength":512},"maxChars":{"type":"integer","exclusiveMinimum":0,"maximum":65536}},"required":["action","maxChars"]}]},"BrowserTarget":{"type":"object","properties":{"role":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":512},"text":{"type":"string","maxLength":512},"selector":{"type":"string","maxLength":512},"nth":{"type":"integer","minimum":0,"maximum":999}}},"QueuedMessage":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"disposition":{"$ref":"#/components/schemas/MessageDisposition"},"enqueuedAt":{"type":"number"},"enqueuedBy":{"type":"string"}},"required":["id","content","disposition","enqueuedAt","enqueuedBy"]},"MessageDisposition":{"type":"string","enum":["queue","steer","stage"]},"MessageDeliveryOutcome":{"type":"object","properties":{"messageId":{"type":"string"},"requested":{"$ref":"#/components/schemas/MessageDisposition"},"applied":{"$ref":"#/components/schemas/MessageDisposition"},"degradedBecause":{"$ref":"#/components/schemas/DispositionDowngradeReason"}},"required":["messageId","requested","applied"]},"DispositionDowngradeReason":{"type":"string","enum":["unsupported","session-idle","not-steerable","not-stageable","turn-owned-elsewhere","pending-interaction"]},"SessionStatus":{"type":"object","properties":{"contextUsage":{"$ref":"#/components/schemas/SessionContextUsage"},"cost":{"type":["number","null"]},"usage":{"$ref":"#/components/schemas/UsageStatus"},"cacheStats":{"$ref":"#/components/schemas/SessionCacheStats"},"model":{"type":["string","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionModeId"},"todoCounts":{"$ref":"#/components/schemas/SessionTodoCounts"},"runningSubagentCount":{"type":"integer","default":0},"lifecycle":{"$ref":"#/components/schemas/SessionLifecycle"},"lastError":{"$ref":"#/components/schemas/ErrorEvent"},"activity":{"$ref":"#/components/schemas/SessionActivity"},"steerable":{"type":"boolean"}},"required":["contextUsage","cost","cacheStats","model","permissionMode","todoCounts","lifecycle"]},"SessionContextUsage":{"type":["object","null"],"properties":{"totalTokens":{"type":"integer"},"maxTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheCreationTokens":{"type":"integer"}},"required":["totalTokens","maxTokens","outputTokens","cacheReadTokens","cacheCreationTokens"]},"SessionActivity":{"type":"object","properties":{"toolName":{"type":"string"},"target":{"type":"string"}},"required":["toolName"]},"SessionUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/Session"},{"type":"object","properties":{"permissionModePendingUntilNextTurn":{"type":"boolean","enum":[true]},"runtimeUnbound":{"type":"boolean","enum":[true]}}}]},"UpdateSessionRequest":{"type":"object","properties":{"permissionMode":{"$ref":"#/components/schemas/PermissionModeId"},"model":{"type":"string"},"effort":{"$ref":"#/components/schemas/EffortLevel"},"fastMode":{"type":"boolean"},"title":{"type":"string","minLength":1,"maxLength":200},"acknowledgedAutonomy":{"type":"boolean"},"runtime":{"type":"string"}}},"SendMessageResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Canonical session id; differs from the request id for a new session"},"messageId":{"type":"string","description":"Server-minted id for this message; the queue is keyed by it"},"outcome":{"$ref":"#/components/schemas/MessageDeliveryOutcome"},"queuePosition":{"type":"integer","exclusiveMinimum":0,"description":"1-based place in the session queue at acceptance; 1 means nothing was ahead of it"}},"required":["sessionId","messageId","outcome","queuePosition"]},"SendMessageRequest":{"type":"object","properties":{"content":{"type":"string","minLength":1},"cwd":{"type":"string"},"correlationId":{"type":"string","format":"uuid"},"clientMessageId":{"type":"string"},"context":{"type":"object","properties":{"uiState":{"$ref":"#/components/schemas/UiState"},"queued":{"type":"boolean"}}},"runtime":{"type":"string"},"account":{"type":"string","minLength":1},"agentPath":{"type":"string"},"workspaceKey":{"type":"string"},"workspaceProvider":{"type":"string","enum":["worktree","clone"]},"seedContext":{"type":"string","minLength":1,"maxLength":10000},"disposition":{"$ref":"#/components/schemas/MessageDisposition"}},"required":["content"]},"UiState":{"type":"object","properties":{"panels":{"type":"object","properties":{"settings":{"type":"boolean"},"tasks":{"type":"boolean"},"relay":{"type":"boolean"},"picker":{"type":"boolean"}},"required":["settings","tasks","relay","picker"]},"sidebar":{"type":"object","properties":{"open":{"type":"boolean"},"activeTab":{"allOf":[{"$ref":"#/components/schemas/UiSidebarTab"},{"type":["string","null"]}]}},"required":["open","activeTab"]},"agent":{"type":"object","properties":{"id":{"type":["string","null"]},"cwd":{"type":["string","null"]}},"required":["id","cwd"]}},"required":["panels","sidebar","agent"]},"SessionQueueResponse":{"type":"object","properties":{"queue":{"type":"array","items":{"$ref":"#/components/schemas/QueuedMessage"}}},"required":["queue"]},"UpdateQueuedMessageResponse":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/QueuedMessage"},"queue":{"type":"array","items":{"$ref":"#/components/schemas/QueuedMessage"}}},"required":["message","queue"]},"UpdateQueuedMessageRequest":{"type":"object","properties":{"content":{"type":"string","minLength":1},"move":{"$ref":"#/components/schemas/QueueMoveTarget"}}},"QueueMoveTarget":{"anyOf":[{"type":"object","properties":{"before":{"type":"string"}},"required":["before"],"additionalProperties":false},{"type":"object","properties":{"after":{"type":"string"}},"required":["after"],"additionalProperties":false}]},"SessionTriggerResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Canonical session id; differs from the request id for a new session"}},"required":["sessionId"]},"ApprovalRequest":{"type":"object","properties":{"toolCallId":{"type":"string"},"alwaysAllow":{"type":"boolean"},"reason":{"type":"string","maxLength":1000}},"required":["toolCallId"]},"SubmitAnswersRequest":{"type":"object","properties":{"toolCallId":{"type":"string"},"answers":{"type":"object","additionalProperties":{"type":"string"}}},"required":["toolCallId","answers"]},"UiActionRequest":{"type":"object","properties":{"widgetId":{"type":"string","maxLength":200},"actionId":{"type":"string","minLength":1,"maxLength":200},"payload":{"type":"object","additionalProperties":{}},"widgetTitle":{"type":"string","maxLength":300},"cwd":{"type":"string"}},"required":["actionId"]},"McpAppResourceResponse":{"type":"object","properties":{"mimeType":{"type":"string"},"text":{"type":"string"},"blob":{"type":"string"},"csp":{"type":"string"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/McpAppPermission"},"default":[]}},"required":["mimeType"]},"McpAppPermission":{"type":"string","enum":["camera","microphone","geolocation","clipboard-write"]},"McpAppResourceRequest":{"type":"object","properties":{"serverName":{"type":"string","minLength":1},"uri":{"type":"string","minLength":1}},"required":["serverName","uri"]},"ModelOption":{"type":"object","properties":{"value":{"type":"string","description":"Model identifier (e.g. claude-opus-4-6)"},"resolvedModel":{"type":"string","description":"Canonical wire model id an alias row resolves to (e.g. sonnet -> claude-sonnet-5). Absent when the row is already a wire id, or when the runtime does not report it."},"displayName":{"type":"string","description":"Human-readable model name"},"description":{"type":"string","description":"Short model description"},"isDefault":{"type":"boolean","description":"Whether this is the default model"},"contextWindow":{"type":"integer","description":"Context window size in tokens"},"supportsEffort":{"type":"boolean","description":"Whether this model supports effort levels"},"supportedEffortLevels":{"type":"array","items":{"$ref":"#/components/schemas/EffortLevel"},"description":"Available effort levels for this model"},"supportsFastMode":{"type":"boolean","description":"Whether this model supports fast mode"},"supportsAutoMode":{"type":"boolean","description":"Whether this model supports auto mode"},"supportsAdaptiveThinking":{"type":"boolean","description":"Claude decides when and how much to think"},"maxOutputTokens":{"type":"integer","description":"Maximum output tokens"},"provider":{"type":"string","description":"Provider identifier (e.g. anthropic, openai)"},"family":{"type":"string","description":"Model family (e.g. claude-4, gpt-5)"},"tier":{"type":"string","enum":["flagship","balanced","fast","specialized","legacy","frontier","solid-coder","quick-helper"],"description":"Model tier for UI grouping"},"local":{"type":"boolean","description":"True when the model runs locally on this machine (e.g. Ollama), so nothing typed leaves the computer"},"supportsVision":{"type":"boolean","description":"Whether the model accepts images as input. Absent means the runtime does not report it."},"supportsToolUse":{"type":"boolean","description":"Whether the model can call tools. `false` means it can only chat — it cannot read files or run commands, so it cannot do agent work. Absent means the runtime does not report it, and the model is treated as capable."},"supportsImageOutput":{"type":"boolean","description":"Whether the model returns generated images rather than only text. Absent means the runtime does not report it."},"unverified":{"type":"boolean","description":"True when this row comes from a shortened, unconfirmed menu — the runtime found no connected provider, so it is offering a bounded guess rather than models it knows you can use. Surfaces have to say so instead of presenting the list as complete."},"supportsStreaming":{"type":"boolean"},"supportsCodeExecution":{"type":"boolean"},"isDeprecated":{"type":"boolean"}},"required":["value","displayName","description"]},"BrowseDirectoryResponse":{"type":"object","properties":{"path":{"type":"string"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/DirectoryEntry"}},"parent":{"type":["string","null"]}},"required":["path","entries","parent"]},"DirectoryEntry":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"isDirectory":{"type":"boolean"}},"required":["name","path","isDirectory"]},"WorkbenchSignResponse":{"type":"object","properties":{"url":{"type":["string","null"]},"unavailable":{"type":"string","enum":["tunnel","no-port"]}},"required":["url"]},"WorkbenchSignRequest":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["serve"]},"cwd":{"type":"string","minLength":1},"path":{"type":"string"}},"required":["kind","cwd"]},{"type":"object","properties":{"kind":{"type":"string","enum":["proxy"]},"port":{"type":"integer","minimum":1,"maximum":65535}},"required":["kind","port"]}]},"WorkbenchProbeResponse":{"type":"object","properties":{"listening":{"type":"boolean"}},"required":["listening"]},"WorkbenchProbeRequest":{"type":"object","properties":{"port":{"type":"integer","minimum":1,"maximum":65535}},"required":["port"]},"CommandRegistry":{"type":"object","properties":{"commands":{"type":"array","items":{"$ref":"#/components/schemas/CommandEntry"}},"lastScanned":{"type":"string"}},"required":["commands","lastScanned"]},"CommandEntry":{"type":"object","properties":{"namespace":{"type":"string"},"command":{"type":"string"},"fullCommand":{"type":"string"},"description":{"type":"string"},"argumentHint":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"allowedTools":{"type":"array","items":{"type":"string"}},"filePath":{"type":"string"}},"required":["fullCommand","description"]},"Task":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":["string","null"]},"description":{"type":["string","null"]},"prompt":{"type":"string"},"cron":{"type":["string","null"]},"timezone":{"type":["string","null"]},"agentId":{"type":["string","null"],"default":null},"enabled":{"type":"boolean"},"sticky":{"type":"boolean","default":false},"maxRuntime":{"type":["integer","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"runtime":{"type":["string","null"],"default":null},"model":{"type":["string","null"],"default":null},"effort":{"allOf":[{"$ref":"#/components/schemas/EffortLevel"},{"type":["string","null"]}]},"status":{"$ref":"#/components/schemas/TaskStatus"},"filePath":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"reason":{"type":["string","null"],"default":null},"proposedBySessionId":{"type":["string","null"],"default":null},"proposedByAgentPath":{"type":["string","null"],"default":null},"proposedByName":{"type":["string","null"],"default":null},"origin":{"type":["string","null"],"enum":["file",null],"default":null},"reasonSource":{"type":["string","null"],"enum":["dorkos",null],"default":null},"nextRun":{"type":["string","null"]},"nextRuns":{"type":"array","items":{"type":"string"},"default":[]}},"required":["id","name","prompt","cron","timezone","enabled","maxRuntime","permissionMode","status","filePath","createdAt","updatedAt"]},"PermissionMode":{"type":"string","enum":["default","plan","acceptEdits","dontAsk","bypassPermissions","auto"]},"TaskStatus":{"type":"string","enum":["active","paused","pending_approval"]},"CreateTaskRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"displayName":{"type":"string"},"description":{"type":"string","minLength":1,"maxLength":1024},"prompt":{"type":"string","minLength":1},"cron":{"type":["string","null"],"minLength":1},"timezone":{"type":["string","null"],"minLength":1},"target":{"type":"string","minLength":1},"enabled":{"type":"boolean","default":true},"maxRuntime":{"type":["string","null"],"minLength":1,"maxLength":32,"pattern":"^(?:\\d+h)?(?:\\d+m)?(?:\\d+s)?$"},"sticky":{"type":"boolean"},"runtime":{"type":["string","null"],"minLength":1},"model":{"type":["string","null"],"minLength":1},"effort":{"allOf":[{"$ref":"#/components/schemas/EffortLevel"},{"type":["string","null"]}]},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"reason":{"type":"string"}},"required":["name","description","prompt","target"]},"UpdateTaskRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"displayName":{"type":["string","null"]},"description":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1},"cron":{"type":["string","null"],"minLength":1},"timezone":{"type":["string","null"],"minLength":1},"enabled":{"type":"boolean"},"maxRuntime":{"type":["string","null"],"minLength":1,"maxLength":32,"pattern":"^(?:\\d+h)?(?:\\d+m)?(?:\\d+s)?$"},"sticky":{"type":"boolean"},"runtime":{"type":["string","null"],"minLength":1},"model":{"type":["string","null"],"minLength":1},"effort":{"allOf":[{"$ref":"#/components/schemas/EffortLevel"},{"type":["string","null"]}]},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"status":{"$ref":"#/components/schemas/SettableTaskStatus"},"reason":{"type":"string"}}},"SettableTaskStatus":{"type":"string","enum":["active","pending_approval"]},"TaskRun":{"type":"object","properties":{"id":{"type":"string"},"scheduleId":{"type":"string"},"status":{"$ref":"#/components/schemas/TaskRunStatus"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"durationMs":{"type":["integer","null"]},"outputSummary":{"type":["string","null"]},"error":{"type":["string","null"]},"sessionId":{"type":["string","null"]},"trigger":{"$ref":"#/components/schemas/TaskRunTrigger"},"resolvedRuntime":{"type":["string","null"],"default":null},"resolvedModel":{"type":["string","null"],"default":null},"createdAt":{"type":"string"}},"required":["id","scheduleId","status","startedAt","finishedAt","durationMs","outputSummary","error","sessionId","trigger","createdAt"]},"TaskRunStatus":{"type":"string","enum":["running","completed","failed","cancelled","skipped"]},"TaskRunTrigger":{"type":"string","enum":["scheduled","manual","agent"]},"CancelTaskRunResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"state":{"type":"string","enum":["stopping","already_finished"]}},"required":["success","state"]},"RelaySendMessageRequest":{"type":"object","properties":{"subject":{"type":"string","minLength":1},"payload":{},"from":{"type":"string","minLength":1},"replyTo":{"type":"string"},"budget":{"type":"object","properties":{"maxHops":{"type":"integer","minimum":1},"ttl":{"type":"integer"},"callBudgetRemaining":{"type":"integer","minimum":0}}}},"required":["subject","from"]},"RelayEnvelope":{"type":"object","properties":{"id":{"type":"string","description":"ULID message ID"},"subject":{"type":"string"},"from":{"type":"string"},"replyTo":{"type":"string"},"budget":{"$ref":"#/components/schemas/RelayBudget"},"createdAt":{"type":"string","format":"date-time"},"payload":{},"dispatchId":{"type":"string","description":"Opaque correlation id joining every hop of one dispatch"}},"required":["id","subject","from","budget","createdAt"]},"RelayBudget":{"type":"object","properties":{"hopCount":{"type":"integer","minimum":0},"maxHops":{"type":"integer","minimum":1,"default":5},"ancestorChain":{"type":"array","items":{"type":"string"}},"ttl":{"type":"integer","minimum":0,"description":"Absolute expiry timestamp (ms since epoch)"},"callBudgetRemaining":{"type":"integer","minimum":0}},"required":["hopCount","ancestorChain","ttl","callBudgetRemaining"]},"EndpointRegistration":{"type":"object","properties":{"subject":{"type":"string","minLength":1},"description":{"type":"string"}},"required":["subject"]},"InboxStatusFilter":{"type":"string","enum":["pending","delivered","failed","all"],"default":"pending","description":"Filter messages by status. Defaults to \"pending\" (deliverable, unread messages) so budget-rejected failures never surface silently next to real deliverables. Pass \"failed\" to see budget-rejected/dead-lettered messages, \"delivered\" for already-read ones (metadata only — the payload is removed once a message completes), or \"all\" for every status."},"DiscoveryCandidate":{"type":"object","properties":{"path":{"type":"string","minLength":1},"strategy":{"type":"string","minLength":1},"hints":{"$ref":"#/components/schemas/AgentHints"},"discoveredAt":{"type":"string","format":"date-time"}},"required":["path","strategy","hints","discoveredAt"]},"AgentHints":{"type":"object","properties":{"suggestedName":{"type":"string"},"detectedRuntime":{"$ref":"#/components/schemas/AgentRuntime"},"inferredCapabilities":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["suggestedName","detectedRuntime"]},"AgentRuntime":{"type":"string","enum":["claude-code","cursor","codex","opencode","windsurf","gemini","cline","roo-code","copilot","amazon-q","continue","augment","jetbrains-ai","kilo-code","trae","other"]},"DiscoverRequest":{"type":"object","properties":{"roots":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"maxDepth":{"type":"integer","minimum":1}},"required":["roots"]},"AgentManifest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"ULID assigned at registration"},"name":{"type":"string","minLength":1},"displayName":{"type":"string","maxLength":100,"description":"Human-readable display name. Falls back to name (slug) when absent.","example":"My Cool Agent"},"description":{"type":"string","default":""},"runtime":{"$ref":"#/components/schemas/AgentRuntime"},"capabilities":{"type":"array","items":{"type":"string"},"default":[]},"behavior":{"$ref":"#/components/schemas/AgentBehavior"},"namespace":{"type":"string","maxLength":64},"registeredAt":{"type":"string","format":"date-time"},"registeredBy":{"type":"string","minLength":1},"persona":{"type":"string","maxLength":4000,"description":"System prompt persona text injected into Claude sessions","example":"You are backend-bot, an expert in REST API design..."},"personaEnabled":{"type":"boolean","default":true,"description":"Whether persona text is injected into system prompt"},"traits":{"$ref":"#/components/schemas/Traits"},"conventions":{"$ref":"#/components/schemas/Conventions"},"color":{"type":"string","description":"CSS color override for visual identity (e.g., \"#6366f1\")","example":"#6366f1"},"icon":{"type":"string","description":"Emoji override for visual identity","example":"🤖"},"isSystem":{"type":"boolean","default":false,"description":"System agents are auto-managed and cannot be deleted"},"model":{"type":"string","description":"Model new sessions for this agent start on, in its own runtime's id space. Absent = inherit the server default.","example":"opus"},"effort":{"type":"string","enum":["none","minimal","low","medium","high","max","xhigh"],"description":"Reasoning effort new sessions for this agent start at. Absent = inherit the server default.","example":"high"},"account":{"type":"string","description":"Claude Code account new sessions for this agent run and bill on, as a registry id (runtimes.claudeCode.accounts[].id). Absent = inherit the server default. Operator-only: agents cannot set this on themselves or on each other.","example":"acme-corp"},"enabledToolGroups":{"$ref":"#/components/schemas/EnabledToolGroups"},"tierCeiling":{"type":"string","enum":["observe","act","destructive"],"description":"The most this agent is ever allowed to do. 'observe' is read-only, 'act' can change things but never delete them, 'destructive' has no extra limit. Absent means no extra limit. Nobody can approve past it — an agent capped at 'act' is refused a destructive capability outright. An agent may lower its own ceiling; only a person can raise one.","example":"act"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"},"default":[]},"workspace":{"type":"object","description":"Where this agent works. Absent, or unreadable, means its own folder. 'managed' gives it a private checkout of a repository; 'none' means it uses whatever folder the session is opened in.","properties":{"mode":{"type":"string","enum":["home","managed","none"]},"source":{"type":"string","description":"Repository or directory the checkout is made from ('managed' only)."},"provider":{"type":"string","enum":["worktree","clone"]}},"required":["mode"],"example":{"mode":"home"}}},"required":["id","name","runtime","registeredAt","registeredBy"]},"AgentBehavior":{"type":"object","properties":{"responseMode":{"type":"string","enum":["always","engaged","direct-only","mention-only","silent"],"default":"always"},"escalationThreshold":{"type":"number"}},"default":{"responseMode":"always"}},"Traits":{"type":"object","properties":{"verbosity":{"type":"integer","minimum":1,"maximum":5,"default":3},"autonomy":{"type":"integer","minimum":1,"maximum":5,"default":3},"chaos":{"type":"integer","minimum":1,"maximum":5,"default":3},"creativity":{"type":"integer","minimum":1,"maximum":5,"default":3},"humor":{"type":"integer","minimum":1,"maximum":5,"default":3},"spice":{"type":"integer","minimum":1,"maximum":5,"default":3}}},"Conventions":{"type":"object","properties":{"soul":{"type":"boolean","default":true},"nope":{"type":"boolean","default":true},"memory":{"type":"boolean","default":true},"dorkosKnowledge":{"type":"boolean","default":true}}},"EnabledToolGroups":{"type":"object","properties":{"tasks":{"type":"boolean"},"relay":{"type":"boolean"},"mesh":{"type":"boolean"},"adapter":{"type":"boolean"},"roomsManage":{"type":"boolean"}},"default":{},"description":"Per-agent tool groups. The four domain keys (tasks, relay, mesh, adapter) are documentation settings: undefined = inherit global default, and off means the agent is not told about the group, not that the tools are blocked. Binding tools follow adapter toggle. Trace tools follow relay toggle. roomsManage is different: it is a per-agent grant the server enforces, and absent means off with no global default. Only a person sets any of the five: the agent-reachable write path refuses this object outright."},"ManagedMcpServer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"enabled":{"type":"boolean","default":false},"connection":{"oneOf":[{"type":"object","properties":{"transport":{"type":"string","enum":["stdio"]},"command":{"type":"string","minLength":1},"args":{"type":"array","items":{"type":"string"},"default":[]},"env":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}}},"required":["transport","command"]},{"type":"object","properties":{"transport":{"type":"string","enum":["http"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]},{"type":"object","properties":{"transport":{"type":"string","enum":["sse"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]}]},"addedAt":{"type":"string","format":"date-time"},"addedBy":{"type":"string","minLength":1}},"required":["name","connection","addedAt","addedBy"]},"RegisterAgentRequest":{"type":"object","properties":{"path":{"type":"string","minLength":1},"overrides":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"ULID assigned at registration"},"name":{"type":"string","minLength":1},"displayName":{"type":"string","maxLength":100,"description":"Human-readable display name. Falls back to name (slug) when absent.","example":"My Cool Agent"},"description":{"type":"string","default":""},"runtime":{"$ref":"#/components/schemas/AgentRuntime"},"capabilities":{"type":"array","items":{"type":"string"},"default":[]},"behavior":{"$ref":"#/components/schemas/AgentBehavior"},"namespace":{"type":"string","maxLength":64},"registeredAt":{"type":"string","format":"date-time"},"registeredBy":{"type":"string","minLength":1},"persona":{"type":"string","maxLength":4000,"description":"System prompt persona text injected into Claude sessions","example":"You are backend-bot, an expert in REST API design..."},"personaEnabled":{"type":"boolean","default":true,"description":"Whether persona text is injected into system prompt"},"traits":{"$ref":"#/components/schemas/Traits"},"conventions":{"$ref":"#/components/schemas/Conventions"},"color":{"type":"string","description":"CSS color override for visual identity (e.g., \"#6366f1\")","example":"#6366f1"},"icon":{"type":"string","description":"Emoji override for visual identity","example":"🤖"},"isSystem":{"type":"boolean","default":false,"description":"System agents are auto-managed and cannot be deleted"},"model":{"type":"string","description":"Model new sessions for this agent start on, in its own runtime's id space. Absent = inherit the server default.","example":"opus"},"effort":{"type":"string","enum":["none","minimal","low","medium","high","max","xhigh"],"description":"Reasoning effort new sessions for this agent start at. Absent = inherit the server default.","example":"high"},"account":{"type":"string","description":"Claude Code account new sessions for this agent run and bill on, as a registry id (runtimes.claudeCode.accounts[].id). Absent = inherit the server default. Operator-only: agents cannot set this on themselves or on each other.","example":"acme-corp"},"enabledToolGroups":{"$ref":"#/components/schemas/EnabledToolGroups"},"tierCeiling":{"type":"string","enum":["observe","act","destructive"],"description":"The most this agent is ever allowed to do. 'observe' is read-only, 'act' can change things but never delete them, 'destructive' has no extra limit. Absent means no extra limit. Nobody can approve past it — an agent capped at 'act' is refused a destructive capability outright. An agent may lower its own ceiling; only a person can raise one.","example":"act"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"},"default":[]},"workspace":{"type":"object","description":"Where this agent works. Absent, or unreadable, means its own folder. 'managed' gives it a private checkout of a repository; 'none' means it uses whatever folder the session is opened in.","properties":{"mode":{"type":"string","enum":["home","managed","none"]},"source":{"type":"string","description":"Repository or directory the checkout is made from ('managed' only)."},"provider":{"type":"string","enum":["worktree","clone"]}},"required":["mode"],"example":{"mode":"home"}}}},"approver":{"type":"string"},"scanRoot":{"type":"string","minLength":1}},"required":["path"]},"UpdateAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"displayName":{"type":"string","maxLength":100,"description":"Human-readable display name. Falls back to name (slug) when absent.","example":"My Cool Agent"},"description":{"type":"string","default":""},"runtime":{"$ref":"#/components/schemas/AgentRuntime"},"capabilities":{"type":"array","items":{"type":"string"},"default":[]},"behavior":{"$ref":"#/components/schemas/AgentBehavior"},"namespace":{"type":"string","maxLength":64},"persona":{"type":"string","maxLength":4000,"description":"System prompt persona text injected into Claude sessions","example":"You are backend-bot, an expert in REST API design..."},"personaEnabled":{"type":"boolean","default":true,"description":"Whether persona text is injected into system prompt"},"traits":{"$ref":"#/components/schemas/Traits"},"conventions":{"$ref":"#/components/schemas/Conventions"},"color":{"type":["string","null"]},"icon":{"type":["string","null"]},"model":{"type":["string","null"],"minLength":1},"effort":{"type":["string","null"],"enum":["none","minimal","low","medium","high","max","xhigh",null]},"account":{"type":["string","null"],"minLength":1},"enabledToolGroups":{"$ref":"#/components/schemas/EnabledToolGroups"},"tierCeiling":{"type":["string","null"],"enum":["observe","act","destructive",null]}}},"TopologyView":{"type":"object","properties":{"callerNamespace":{"type":"string"},"namespaces":{"type":"array","items":{"$ref":"#/components/schemas/NamespaceInfo"}},"accessRules":{"type":"array","items":{"$ref":"#/components/schemas/CrossNamespaceRule"}},"openMesh":{"type":"boolean","default":false}},"required":["callerNamespace","namespaces","accessRules"]},"NamespaceInfo":{"type":"object","properties":{"namespace":{"type":"string"},"agentCount":{"type":"integer"},"agents":{"type":"array","items":{"$ref":"#/components/schemas/TopologyAgent"}}},"required":["namespace","agentCount","agents"]},"TopologyAgent":{"allOf":[{"$ref":"#/components/schemas/AgentManifest"},{"type":"object","properties":{"projectPath":{"type":"string"},"healthStatus":{"$ref":"#/components/schemas/AgentHealthStatus"},"relayAdapters":{"type":"array","items":{"type":"string"},"default":[]},"relaySubject":{"type":["string","null"],"default":null},"taskCount":{"type":"integer","default":0},"lastSeenAt":{"type":["string","null"],"default":null},"lastSeenEvent":{"type":["string","null"],"default":null}}}]},"AgentHealthStatus":{"type":"string","enum":["active","inactive","stale","unreachable"],"default":"stale"},"CrossNamespaceRule":{"type":"object","properties":{"sourceNamespace":{"type":"string"},"targetNamespace":{"type":"string"},"action":{"type":"string","enum":["allow","deny"]},"origin":{"type":"string","enum":["default","explicit"],"default":"explicit"}},"required":["sourceNamespace","targetNamespace","action"]},"UpdateAccessRuleRequest":{"type":"object","properties":{"sourceNamespace":{"type":"string","minLength":1},"targetNamespace":{"type":"string","minLength":1},"action":{"type":"string","enum":["allow","deny"]}},"required":["sourceNamespace","targetNamespace","action"]},"DenyRequest":{"type":"object","properties":{"path":{"type":"string","minLength":1},"reason":{"type":"string"},"denier":{"type":"string"}},"required":["path"]},"DenialRecord":{"type":"object","properties":{"path":{"type":"string","minLength":1},"reason":{"type":"string"},"deniedBy":{"type":"string","minLength":1},"deniedAt":{"type":"string","format":"date-time"}},"required":["path","deniedBy","deniedAt"]},"ApplyShapeResult":{"type":"object","properties":{"ok":{"type":"boolean"},"applied":{"type":"object","properties":{"layout":{"type":"object","properties":{"sidebarOpen":{"type":"boolean"},"sidebarTab":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$","description":"Sidebar tab id, e.g. a built-in ('overview', 'sessions', 'schedules', 'connections'). The sidebar tab strip exists only in the embedded (Obsidian) app; in the web app switching a sidebar tab is a no-op."},"openPanels":{"type":"array","items":{"type":"string","enum":["settings","tasks","relay","picker"]}},"focusDashboardSections":{"type":"array","items":{"type":"string"}}},"required":["sidebarOpen","openPanels","focusDashboardSections"]},"activatedExtensions":{"type":"array","items":{"type":"string"}},"deactivatedExtensions":{"type":"array","items":{"type":"string"}},"schedulesCreated":{"type":"array","items":{"type":"string"}},"schedulesRebound":{"type":"array","items":{"type":"string"}},"schedulesRemoved":{"type":"array","items":{"type":"string"}}},"required":["layout","activatedExtensions","schedulesCreated","schedulesRebound"]},"warnings":{"type":"array","items":{"type":"string"}},"offeredAgents":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"affinity":{"type":"string","enum":["suggested","default"]},"satisfied":{"type":"boolean"},"arrival":{"type":"boolean"},"autoFollow":{"type":"boolean"},"agentId":{"type":"string"},"projectPath":{"type":"string"},"displayName":{"type":"string"},"template":{"type":"object","additionalProperties":{}},"scheduleSummary":{"type":"string"}},"required":["ref","affinity","satisfied","arrival","autoFollow","displayName"]}}},"required":["ok","applied","warnings","offeredAgents"]},"ForkShapeResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"name":{"type":"string"},"forkedFrom":{"type":"string"},"installPath":{"type":"string"},"manifest":{"type":"object","additionalProperties":{}}},"required":["ok","name","forkedFrom","installPath","manifest"]},"ForkShapeRequest":{"type":"object","properties":{"as":{"type":"string","minLength":1,"description":"New Shape name (kebab-case). Defaults to `-fork`."},"captureCurrent":{"type":"boolean","description":"Snapshot the live arrangement (enabled extensions + chrome) when forking the active Shape."},"liveLayout":{"$ref":"#/components/schemas/ShapeLiveLayoutCapture"}}},"ShapeLiveLayoutCapture":{"type":"object","properties":{"sidebarOpen":{"type":"boolean","description":"Whether the sidebar is open right now."},"sidebarTab":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$","description":"The selected sidebar tab. Report it only where the person picked a tab from a sidebar tab strip the host renders; omit it otherwise, and the source Shape's value is kept."},"openPanels":{"type":"array","items":{"type":"string","enum":["settings","tasks","relay","picker"]},"description":"Panels open right now."},"focusDashboardSections":{"type":"array","items":{"type":"string"},"description":"Dashboard sections to order first. No client observes this today."}},"description":"The client’s live chrome, merged field-wise over the source Shape’s layout. Only honored alongside `captureCurrent` on the active Shape."},"BindingResponse":{"type":"object","properties":{"binding":{"$ref":"#/components/schemas/AdapterBinding"}},"required":["binding"]},"AdapterBinding":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"adapterId":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"chatId":{"type":"string"},"channelType":{"$ref":"#/components/schemas/ChannelType"},"platformChatType":{"$ref":"#/components/schemas/PlatformChatType"},"sessionStrategy":{"$ref":"#/components/schemas/SessionStrategy"},"label":{"type":"string","default":""},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"enabled":{"type":"boolean","default":true},"canInitiate":{"type":"boolean","default":false},"canReply":{"type":"boolean","default":true},"canReceive":{"type":"boolean","default":true},"notifyOnTaskComplete":{"type":"boolean","default":true},"bridge":{"type":"string","enum":["off","room"],"default":"off"},"roomId":{"type":["string","null"],"default":null},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","adapterId","agentId","createdAt","updatedAt"]},"ChannelType":{"type":"string","enum":["dm","group","channel","thread"]},"PlatformChatType":{"type":"string","enum":["private","group","supergroup","channel"]},"SessionStrategy":{"type":"string","enum":["per-chat","per-user","stateless"],"default":"per-chat"},"MoveBindingRequest":{"type":"object","properties":{"agentId":{"type":"string","minLength":1}},"required":["agentId"]},"UnclaimedChatListResponse":{"type":"object","properties":{"chats":{"type":"array","items":{"$ref":"#/components/schemas/UnclaimedChat"}}},"required":["chats"]},"UnclaimedChat":{"type":"object","properties":{"id":{"type":"string"},"adapterId":{"type":"string"},"chatId":{"type":"string"},"channelType":{"allOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":["string","null"]}]},"chatKind":{"type":"string","enum":["dm","group"]},"platformChatType":{"allOf":[{"$ref":"#/components/schemas/PlatformChatType"},{"type":["string","null"]}]},"senderName":{"type":["string","null"],"maxLength":200},"senderId":{"type":["string","null"]},"chatTitle":{"type":["string","null"],"maxLength":200},"status":{"$ref":"#/components/schemas/UnclaimedChatStatus"},"messageCount":{"type":"integer","minimum":0},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"decidedAt":{"type":["string","null"],"format":"date-time"},"decidedAgentId":{"type":["string","null"]}},"required":["id","adapterId","chatId","channelType","chatKind","platformChatType","senderName","senderId","chatTitle","status","messageCount","firstSeenAt","lastSeenAt","decidedAt","decidedAgentId"]},"UnclaimedChatStatus":{"type":"string","enum":["pending","claimed","ignored","blocked"]},"ClaimUnclaimedChatResponse":{"type":"object","properties":{"binding":{"$ref":"#/components/schemas/AdapterBinding"},"bridgeError":{"type":"string"}},"required":["binding"]},"ClaimUnclaimedChatRequest":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"sessionStrategy":{"$ref":"#/components/schemas/SessionStrategy"},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"label":{"type":"string"},"bridge":{"type":"boolean"}},"required":["agentId"]},"PendingApprovalsResponse":{"type":"object","properties":{"approvals":{"type":"array","items":{"$ref":"#/components/schemas/PendingApproval"}}},"required":["approvals"]},"ApprovalDecisionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"approvalId":{"type":"string"},"outcome":{"type":"string","enum":["granted","denied"]},"standingPermission":{"$ref":"#/components/schemas/StandingPermission"}},"required":["ok","approvalId","outcome"]},"StandingPermission":{"type":"object","properties":{"grantId":{"type":"string"},"agentPath":{"type":"string"},"agentLabel":{"type":"string"},"capabilityId":{"type":"string"},"capabilityTitle":{"type":"string"},"expiresAt":{"type":"string"}},"required":["grantId","agentPath","agentLabel","capabilityId","capabilityTitle","expiresAt"]},"StandingPermissionNotRecordedResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["STANDING_PERMISSION_NOT_RECORDED"]},"approvalId":{"type":"string"},"outcome":{"type":"string","enum":["granted"]}},"required":["error","code","approvalId","outcome"]},"GrantApprovalBody":{"type":"object","properties":{"standing":{"type":"boolean"}}},"DenyApprovalBody":{"type":"object","properties":{"reason":{"type":"string","maxLength":1024}}},"StandingPermissionsResponse":{"type":"object","properties":{"grants":{"type":"array","items":{"$ref":"#/components/schemas/StandingPermission"}}},"required":["grants"]},"RevokeStandingPermissionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"grantId":{"type":"string"}},"required":["ok","grantId"]},"RoomListResponse":{"type":"object","properties":{"rooms":{"type":"array","items":{"$ref":"#/components/schemas/RoomSummary"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/RoomListWarning"},"description":"Communities that could not contribute to this list, each already carrying the sentence to show. Empty is the normal case; a non-empty entry is never a reason to hide the rooms that did list."}},"required":["rooms","warnings"]},"RoomSummary":{"allOf":[{"$ref":"#/components/schemas/Room"},{"type":"object","properties":{"unreadCount":{"type":["integer","null"],"minimum":0},"participants":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AuthorRef"},"description":"Direct messages only: the DM's resolved roster. `null` — never `[]` — for a channel, meaning \"not carried here\". A DM's mark IS whoever it is with, so a sidebar that did not get the roster could only hash the room id and draw a stranger; a DM's roster is whoever one person assembled by hand, which is small enough to ride along on every list. A channel reads as `#slug`, so its roster would be payload nothing renders — and a channel's roster is the one with no ceiling on it."},"working":{"type":"integer","minimum":0,"description":"How many agents are working in this room right now — `0` when nobody is. The server always sends it; it is optional only so a caller that predates it still parses. It is a live read of the dispatcher's claim map at the moment of the request, not stored state, so it is the same fact the `room_presence` stream carries and exists purely so a freshly loaded sidebar draws its dots without waiting for the next republish tick."},"viewerHasPosted":{"type":"boolean","description":"Whether the viewer has ever written in this room themselves. Derived from the log on every read, so it cannot drift; membership does not imply it and neither does reading. The server always sends it, and it is optional for the same reason `working` is — a caller that predates it still parses. **Absent means \"this source cannot say\", never `false`**: a client reads it to decide whether to nudge somebody to say hello, and a missing field read as \"never posted\" would nudge an operator who has been talking in #team for months."}},"required":["unreadCount","participants"]}]},"RoomKind":{"type":"string","enum":["channel","dm"]},"AuthorRef":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque author id (ULID). Stable across agent re-registration."},"kind":{"$ref":"#/components/schemas/AuthorKind"},"displayName":{"type":"string","minLength":1},"emoji":{"type":"string","description":"Render cache: the emoji avatar, when the author has one."},"color":{"type":"string","description":"Render cache: the identity colour, when the author has one."},"imageUrl":{"type":"string","description":"Render cache: the author's photo, when they have one. The fourth field beside `displayName`, `emoji` and `color`, on exactly their lifecycle — refreshed by a resolve whose caller knows it, never a key. Additive: an author with a photo AND an emoji keeps both, and the renderer picks. Source-agnostic: the value is whatever URL the avatar store returned, so it may be server-relative today and absolute tomorrow."},"agentRef":{"type":"string","description":"Agents only: the stable handle from `agentAuthorRef(agentPath)`. Compare this, never a display name."},"handle":{"type":["string","null"],"description":"This author's address: what to type after an `@` to reach them. Globally unique on this install (case-folded), lowercase, 2–32 characters of `[a-z0-9._-]`, starting and ending alphanumeric. A mention picker inserts it verbatim, so the string written is the string the server resolves. `null` means this author cannot be addressed by `@` at all — a person who has not chosen one yet, or an agent whose name spells nothing legal. Never fall back to the display name: that is not an address, it is unrestricted text, and it routinely contains spaces the mention pattern cannot span."}},"required":["id","kind","displayName","handle"]},"AuthorKind":{"type":"string","enum":["human","agent","system"]},"Room":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/RoomKind"},"slug":{"type":["string","null"],"description":"Channels only. Unique among non-archived channels."},"title":{"type":"string","minLength":1},"topic":{"type":["string","null"]},"archived":{"type":"boolean"},"ambientMaxEntries":{"type":"integer","minimum":0,"description":"How many entries of ambient history a turn in this room replays at most, oldest dropped first (room-participation spec §8.3). A bound on what one turn reads, never on the log — a room never forgets what was said, and a turn whose window was trimmed is told so."},"wellKnown":{"type":["string","null"],"description":"The stable name a room DorkOS itself depends on is found by — `'team'` for the #team channel every install gets at boot — and `null` for every room a person or an agent opened (team-room-home spec D3.1). It is also the tell that this is a SYSTEM room: only the owner may rename or archive one, so a client draws those controls off this field rather than guessing. It never changes, which is what makes it findable after a rename. The server always sends it, `null` included; it is optional only so that the thirty client fixtures that assemble a room by hand need not each carry a field none of them reads. Absent and `null` mean the same thing — an ordinary room."},"fallbackSeatAuthorId":{"type":["string","null"],"description":"The one member that answers a message somebody typed in this room without addressing anybody — #team's default agent (team-room-home spec D3.4) — and `null` in every room a person opened. Held on the room rather than read off a member's `always` mode, because a person may set any agent to \"Everything\" themselves and that choice must not be mistaken for this one. Optional for the same reason `wellKnown` is: client fixtures that assemble a room by hand do not carry a field they never read, and absent means the same as `null`."},"turnLimitsEnabled":{"type":["boolean","null"],"description":"Whether automatic replies are limited in THIS room. `false` makes it unlimited even when the install limits every other room; `true` keeps it limited when the install does not; `null` inherits `rooms.turnLimitsEnabled`. A room opts out of its own bounds, never out of the install-wide hourly ceiling — that one still applies unless it is turned off in Settings."},"maxAgentDepth":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"How many replies in a row agents may send each other in this room before it stops them, or `null` to inherit `rooms.maxAgentDepth`."},"maxTurnsPerAgentPerCascade":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"How many TURNS any ONE agent may take here, or `null` to inherit `rooms.maxTurnsPerAgentPerCascade`. Progress notes an agent posts mid-turn do not count extra."},"maxAutoTurnsPerHour":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"The most automatic replies this room may run in an hour, or `null` to inherit `rooms.maxAutomaticTurnsPerRoomPerHour`. There is no per-room twin of the install-wide hourly total: that one bounds the whole install and is set in Settings alone."},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"},"bridge":{"type":["object","null"],"properties":{"visibility":{"type":["string","null"],"enum":["partial","full",null],"description":"Telegram's privacy-mode switch: 'partial' (mentions/commands/replies only) or 'full' (everything). `null` for a bridged DM, or a group whose first visibility check has not yet completed."},"platformTitle":{"type":["string","null"],"description":"The platform chat's title, sanitized, as recorded when this room was bridged (spec §3.4). A room's own `title` can be renamed afterward without this column moving with it, which is the whole reason to carry it: the room sheet shows this alongside the room's title so the two are never silently different things. `null` for a bridged DM."}},"required":["visibility","platformTitle"],"description":"This room's bridge, and `null` when it has none. `GET /api/rooms`, `GET /api/rooms/:id` and the room-create responses all populate it, so on any of those `null` means \"not bridged\" — the sidebar reads it to tell a direct message somebody made by hand from one a bridged private chat projects. Still optional, for the one reason a field like this stays optional: a client fixture that assembles a room by hand need not carry it, and a caller that predates it still parses. Absent means \"this source did not say\", never `false`."}},"required":["id","kind","slug","title","topic","archived","ambientMaxEntries","createdAt","lastActivityAt"]},"RoomListWarning":{"type":"object","properties":{"community":{"type":"string","minLength":1,"description":"The community that degraded."},"label":{"type":"string","minLength":1,"description":"What a person calls that community."},"message":{"type":"string","minLength":1,"description":"Plain language, already safe to render — never a raw protocol string."}},"required":["community","label","message"]},"ThreadListResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/ThreadSummary"}}},"required":["threads"]},"ThreadSummary":{"type":"object","properties":{"roomId":{"type":"string","minLength":1},"roomKind":{"$ref":"#/components/schemas/RoomKind"},"roomSlug":{"type":["string","null"],"description":"Channels only, as on the room itself."},"roomTitle":{"type":"string","minLength":1},"rootEntryId":{"type":"string","minLength":1,"description":"The entry the thread hangs off."},"rootAuthorId":{"type":"string","minLength":1},"rootPreview":{"type":"string","description":"The root's text, truncated to 160 characters. Empty when the root carried no text — a row draws a placeholder rather than pretending the message was blank."},"replyCount":{"type":"integer","minimum":1,"description":"Replies below the root. Never counts the root."},"unreadCount":{"type":"integer","minimum":0,"description":"Replies above the reader's `(member, room)` read cursor. Opening the room clears this, exactly as it clears the room's own badge: there is one cursor per (member, room) and threads share it. A reply of the reader's OWN counts while it sits above that cursor — unread is measured against the cursor and nothing else, which is how `countUnread` measures the room's badge, and one rule measured in one place is worth more here than a special case for your own words. In practice the room you just wrote in is the room you have open, so the cursor passes it immediately."},"lastActivityAt":{"type":"string","description":"The newest reply's timestamp. The list is sorted on it."}},"required":["roomId","roomKind","roomSlug","roomTitle","rootEntryId","rootAuthorId","rootPreview","replyCount","unreadCount","lastActivityAt"]},"RoomWithRoster":{"allOf":[{"$ref":"#/components/schemas/Room"},{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/RoomRosterEntry"}},"viewerAuthorId":{"type":"string","minLength":1,"description":"The author id the server resolved for THIS request — who the reader is. Match a roster member on it to find your own membership (your read cursor, your response mode); never match on `author.kind`. It is not necessarily on `members`: seeing a room and being in it are different things."},"viewerIsOperator":{"type":"boolean","description":"Whether THIS reader is the person who owns this install — the one gate that is not a membership. It rides the room read for the same reason `viewerAuthorId` does: the reader is already resolved here, and nothing else on the wire tells a client, so every operator-only affordance in a room had to be drawn for everybody and refused afterwards. **Absent means \"this source cannot say\", never `false`** — a caller that predates it still parses, and a screen reading it as a denial would hide the action from the one person who can take it. Used by the merge action on a room worktree diff (spec `canvas-agent-seat` §8); the server still refuses a non-operator, so this only decides what is drawn."},"reactionFrequents":{"type":"array","items":{"type":"string"},"description":"THIS reader's most-used reaction emoji, most-used first, always exactly three — the quick row in the message capsule. Counted across every room, because a person's reaction habits are theirs and not a room's, and padded from the shipped defaults so a new install still gets a full row. It rides the room rather than a route of its own for the same reason `viewerAuthorId` does: the reader is already resolved here, the value is one aggregate query, and a capsule that had to fetch it separately would draw an empty row first."},"deliverNotices":{"type":"boolean","description":"Present only on a bridged room: whether a turn_failed or halted notice reaches the bridged chat (chats-as-channels spec §6.2, D-6 Q5). The one per-bridge override, seeded true for a DM and false for a channel. Absent on any room with no bridge — the field IS the tell that this room projects to an external chat, so the DorkOS app's bridge controls read their state from it."},"workingAgents":{"type":"array","items":{"$ref":"#/components/schemas/RoomWorkingClaim"},"description":"Who is mid-turn in this room right now, one row per agent, oldest claim first. `[]` means nobody is, and the server always sends it — it is optional only so a caller that predates it still parses, and **absent means \"this source cannot say\", never \"nobody\"**. A live read of the dispatcher's claim map, so it is the same fact the `room_presence` signal carries; it rides the room read so a room opened mid-turn draws its working rows on the first paint instead of waiting up to 10s for the next republish. Named apart from `RoomSummary.working`, which answers the same question with a bare COUNT for a sidebar that draws a dot: the two shapes are routinely spread into one another, so one name for two types would be a silent mismatch rather than a caught one."}},"required":["members","viewerAuthorId","reactionFrequents"]}]},"RoomRosterEntry":{"allOf":[{"$ref":"#/components/schemas/RoomMember"},{"type":"object","properties":{"author":{"$ref":"#/components/schemas/AuthorRef"},"origin":{"$ref":"#/components/schemas/AuthorOrigin"}},"required":["author","origin"]}]},"AuthorOrigin":{"anyOf":[{"type":"string","enum":["local"],"description":"This machine: the operator, an agent, or the room itself."},{"type":"object","properties":{"platform":{"type":"string","minLength":1}},"required":["platform"],"description":"Outside this machine, on the named platform."}],"description":"Where this member is: on this machine, or on the platform a bridged chat projects from. Derived from the stored author key, so it is a property of who they are and not of how this response was produced."},"RoomMember":{"type":"object","properties":{"roomId":{"type":"string","minLength":1},"authorId":{"type":"string","minLength":1},"responseMode":{"type":"string","enum":["always","engaged","direct-only","mention-only","silent"],"description":"Per-room override, written explicitly at join time. Seeded from the manifest for a DM and \"engaged\" for a channel. A thread is a position inside a channel rather than a room of its own, so a reply there reads the channel's value — but the engaged window itself is thread-scoped, so being addressed in a thread does not engage the agent across the whole channel."},"joinedAt":{"type":"string"},"joinedSeq":{"type":"integer","minimum":0,"description":"The room's highest seq when this membership was written — 0 for somebody who joined an empty room. The floor under everything the member may be shown: joining a channel does not retroactively read what was said before you were in it. Distinct from `lastReadSeq`, which starts at 0 for everybody and moves as they read."},"lastReadSeq":{"type":"integer","minimum":0,"description":"Where this member has read up to in this room. For a PERSON it is their own read state, shared with every other device they read on; for an AGENT it is what the room has shown it, which its next ambient turn reads from. One number either way — match yourself on `RoomWithRoster.viewerAuthorId` and this is your place in the room."}},"required":["roomId","authorId","responseMode","joinedAt","joinedSeq","lastReadSeq"]},"RoomWorkingClaim":{"type":"object","properties":{"authorId":{"type":"string","minLength":1,"description":"The agent holding the claim, as a roster author id."},"since":{"type":"string","description":"ISO 8601 — when its turn started, never when this response was built. It is what lets a freshly opened room draw \"4m\" rather than \"0s\" corrected a second later."}},"required":["authorId","since"]},"CreateRoomRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["channel","dm"],"description":"A thread is not a room: it is a relation between entries, written by replying with POST /:id/threads (ADR 260728-022013)."},"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,79}$"},"topic":{"type":"string","maxLength":500},"members":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Author ids to seed the roster with, besides the creator."},"agentPaths":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Agent directories to seed the roster with, minting an author row for any agent that has never been in a room. The DorkOS app knows agents by path and not by author id, so without this a DM takes two calls and a failed second one leaves a room with nobody in it. A DM may name any number of agents: one gives a one-to-one conversation, several give a group."}},"required":["kind"]},"RoomSessionsResponse":{"type":"object","properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/RoomSessionBinding"}}},"required":["bindings"]},"RoomSessionBinding":{"type":"object","properties":{"authorId":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1}},"required":["authorId","sessionId"]},"UpdateRoomRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"topic":{"type":["string","null"],"maxLength":500},"archived":{"type":"boolean"},"deliverNotices":{"type":"boolean","description":"The one per-bridge override for outbound notices (chats-as-channels spec §6.2, D-6 Q5): whether a turn_failed or halted notice reaches this room's bridged chat. Valid only on a bridged room; a room with no bridge refuses this field with NOT_A_BRIDGED_ROOM."},"turnLimitsEnabled":{"type":["boolean","null"],"description":"Whether automatic replies are limited in THIS room. `false` makes it unlimited even when the install limits every other room; `true` keeps it limited when the install does not; `null` inherits `rooms.turnLimitsEnabled`. A room opts out of its own bounds, never out of the install-wide hourly ceiling — that one still applies unless it is turned off in Settings."},"maxAgentDepth":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"How many replies in a row agents may send each other in this room before it stops them, or `null` to inherit `rooms.maxAgentDepth`."},"maxTurnsPerAgentPerCascade":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"How many TURNS any ONE agent may take here, or `null` to inherit `rooms.maxTurnsPerAgentPerCascade`. Progress notes an agent posts mid-turn do not count extra."},"maxAutoTurnsPerHour":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"The most automatic replies this room may run in an hour, or `null` to inherit `rooms.maxAutomaticTurnsPerRoomPerHour`. There is no per-room twin of the install-wide hourly total: that one bounds the whole install and is set in Settings alone."}}},"RoomEntryListResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/RoomEntry"}},"threadRoots":{"type":"array","items":{"$ref":"#/components/schemas/RoomEntry"},"description":"The thread roots entries in this page reply to that the page itself does not hold, oldest first. Empty whenever every reply's root came back in the page. Never part of the page: each one sits below its oldest entry, so a `before=` cursor is read from `entries` alone. Each carries `threadReplyCount`, because a thread reaching back past the page is also the one case where what a reader loaded is not the whole of it."}},"required":["entries","threadRoots"]},"RoomEntry":{"type":"object","properties":{"roomId":{"type":"string","minLength":1},"seq":{"type":"integer","minimum":1},"id":{"type":"string","minLength":1,"description":"Stable entry id (ULID). What a reaction would attach to."},"authorId":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/RoomEntryKind"},"body":{"$ref":"#/components/schemas/RoomEntryBody"},"mentions":{"type":"array","items":{"type":"string"},"description":"Author ids resolved from @name at write time. Never re-parsed by the client."},"mentionSpans":{"type":"array","items":{"$ref":"#/components/schemas/MentionSpan"},"description":"Where each resolved @mention sits in the raw body, so the client can draw a pill over it without re-parsing the text. One span per written @handle (not deduped like `mentions`), resolved once at write time. Optional for the same reason as `reactions`: the server's internal entry shape and entries that predate the field carry none, and absent should be read as empty — every wire path that carries a local room entry populates it."},"sessionId":{"type":["string","null"]},"cascadeRoot":{"type":"string","minLength":1},"cascadeDepth":{"type":"integer","minimum":0},"parentEntryId":{"type":["string","null"],"description":"The entry in this same room that this one answers, or null for a top-level entry. A thread is a relation between entries, never a room of its own (ADR 260728-022013)."},"threadRootEntryId":{"type":["string","null"],"description":"The entry at the head of this entry's thread, or null when it is top-level — including for a root that has replies, so a thread's reply count never counts its own root. The default timeline is every entry whose parentEntryId is null."},"signature":{"type":["string","null"],"description":"Reserved for phase 4. Always null in v1."},"createdAt":{"type":"string"},"reactions":{"type":"array","items":{"$ref":"#/components/schemas/RoomEntryReaction"},"description":"The entry's reactions right now, oldest pill first. Every path that delivers an entry to a reader carries it — the history page, the stream's hydration snapshot, a resume replay, and a live `entry` event, which carries `[]` because an entry a millisecond old has none. It is optional only because the server's internal entry shape exists before the roll-up runs; on the wire it is always present, and absent should be read as empty."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/RoomAttachment"},"description":"The files posted with this entry. Every path that delivers an entry to a reader carries it — the history page, the stream's hydration snapshot, a resume replay, and a live `entry` event. Optional only because the server's internal entry shape exists before the roll-up runs; on the wire it is always present, and absent should be read as empty."},"threadReplyCount":{"type":"integer","minimum":1,"description":"How many replies this entry's thread holds in the ROOM, which is not always how many the reader has. Unlike the two roll-ups above it, this is present on exactly one kind of entry: a thread root that came back in `threadRoots` because the page it belongs to does not contain it. That is the only case where the replies a client loaded are not the whole thread — a root INSIDE the page has every one of its replies in the page after it, so the loaded replies are the count, and a second number that could disagree with what is on screen would be worse than no number at all. Absent means \"count what you have\"."}},"required":["roomId","seq","id","authorId","kind","body","mentions","sessionId","cascadeRoot","cascadeDepth","parentEntryId","threadRootEntryId","signature","createdAt"]},"RoomEntryKind":{"type":"string","enum":["post","notice"]},"RoomEntryBody":{"type":"object","properties":{"text":{"type":"string"},"notice":{"$ref":"#/components/schemas/RoomNoticeCode"},"subjectAuthorId":{"type":"string"},"moment":{"$ref":"#/components/schemas/RoomMoment"},"merge":{"$ref":"#/components/schemas/RoomMergeEvent"},"canvas":{"$ref":"#/components/schemas/RoomCanvasChange"},"waitingKind":{"$ref":"#/components/schemas/RoomWaitingKind"},"answersEntryId":{"type":"string","description":"The entry this post answers, set on every agent-authored post the room writes for a turn. Chat posts in arrival order whatever a message is responding to, and an agent whose message waited behind work in another conversation answers out of order often rather than rarely — so the pointer is what a reader follows back to the question."}},"required":["text"]},"RoomNoticeCode":{"type":"string","enum":["cascade_stopped","budget_reached","agent_busy","turn_failed","agent_gone","agent_unavailable","agent_left","runtime_gone","agent_declined","awaiting_approval","halted","addressing_changed","bridge_blocked","bridge_undelivered","bridge_rate_limited","bridge_second_agent_refused","bridge_disconnected","bridge_agent_swapped","bridge_history_note"]},"RoomMoment":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/RoomMomentKind"},"source":{"$ref":"#/components/schemas/RoomMomentSource"},"mintedByAgentRef":{"type":["string","null"],"minLength":1,"description":"The `agentAuthorRef` of the agent that minted this moment, or null when DorkOS itself did."}},"required":["kind","source","mintedByAgentRef"]},"RoomMomentKind":{"type":"string","enum":["first_agent","joined_team","first_pr","first_schedule","first_overnight_run","first_connection","volume_mark","anniversary","agent_minted"]},"RoomMomentSource":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/RoomMomentSourceKind"},"ref":{"type":"string","minLength":1,"description":"The record's own identifier — an agent path, a session id, a pull request URL. Never a sentence, and never empty: a source that names nothing is not a source."},"observedAt":{"type":"string","minLength":1,"description":"When the thing actually happened, from the record. Not when this was posted."}},"required":["kind","ref","observedAt"]},"RoomMomentSourceKind":{"type":"string","enum":["agent","pull_request","schedule","session","connection","activity"]},"RoomMergeEvent":{"type":"object","properties":{"branch":{"type":"string","minLength":1,"description":"The agent's branch, `room/`."},"commit":{"type":"string","minLength":1,"description":"The merge commit on the room’s main branch."},"files":{"type":"integer","minimum":0,"description":"How many files the merge touched."},"insertions":{"type":"integer","minimum":0,"description":"Lines added."},"deletions":{"type":"integer","minimum":0,"description":"Lines removed."}},"required":["branch","commit","files","insertions","deletions"]},"RoomCanvasChange":{"type":"object","properties":{"ops":{"type":"array","items":{"type":"object","properties":{"change":{"type":"string","enum":["opened","updated","closed"]},"documentId":{"type":"string","minLength":1},"type":{"type":"string","minLength":1,"description":"The canvas content type, e.g. `diff` or `browser`."},"title":{"type":"string","description":"The document’s label. Another member’s words."}},"required":["change","documentId","type","title"]},"minItems":1}},"required":["ops"]},"RoomWaitingKind":{"type":"string","enum":["approval","question","elicitation"]},"MentionSpan":{"type":"object","properties":{"offset":{"type":"integer","minimum":0,"description":"UTF-16 code-unit offset of the `@` in the raw body text."},"length":{"type":"integer","minimum":1,"description":"Length in UTF-16 code units of the matched `@handle`, `@` included."},"authorId":{"type":"string","minLength":1,"description":"The live author this occurrence resolved to."}},"required":["offset","length","authorId"]},"RoomEntryReaction":{"type":"object","properties":{"emoji":{"$ref":"#/components/schemas/ReactionEmoji"},"authorIds":{"type":"array","items":{"type":"string","minLength":1},"description":"Who reacted with this emoji, in the order they did — and, for two that landed inside the same millisecond, by author id, so two installs holding identical rows draw identical rows rather than leaving the order to whichever index the planner picked. Match against the room roster to render names; an id that is not on it belongs to somebody who has left."},"firstAt":{"type":"string","description":"When the first of these landed. The pill row is ordered by it, so a pill keeps its place as more people join it."}},"required":["emoji","authorIds","firstAt"]},"ReactionEmoji":{"type":"string","description":"One emoji, stored as the string that was sent — grapheme clusters, joiners, skin tones and flags all survive verbatim. There is no enum: an install that only ever accepted a fixed list would have to ship a migration to add a face.","example":"👍"},"RoomAttachment":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"ULID. Stable, unique within the room."},"name":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":1},"size":{"type":"integer","minimum":0},"preview":{"$ref":"#/components/schemas/RoomAttachmentPreview"},"url":{"type":"string","minLength":1,"description":"Where to fetch it. Server-relative today; a remote store would answer an absolute https URL and no renderer changes."}},"required":["id","name","mimeType","size","preview","url"]},"RoomAttachmentPreview":{"type":["string","null"],"enum":["image",null],"description":"Non-null only when the BYTES were verified as that kind. A declared Content-Type never sets this."},"RoomExportLine":{"oneOf":[{"$ref":"#/components/schemas/RoomExportHeader"},{"$ref":"#/components/schemas/RoomExportEntry"},{"$ref":"#/components/schemas/RoomExportSummary"}],"discriminator":{"propertyName":"type","mapping":{"room-export":"#/components/schemas/RoomExportHeader","entry":"#/components/schemas/RoomExportEntry","summary":"#/components/schemas/RoomExportSummary"}}},"RoomExportHeader":{"type":"object","properties":{"type":{"type":"string","enum":["room-export"]},"format":{"type":"string","enum":["dorkos.room-export"]},"version":{"type":"number","enum":[1]},"exportedAt":{"type":"string","description":"When the file was written (ISO 8601)."},"exportedBy":{"$ref":"#/components/schemas/RoomExportAuthor"},"dorkosVersion":{"type":"string","description":"The DorkOS version that wrote it."},"room":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/RoomKind"},"slug":{"type":["string","null"],"description":"Channels only."},"title":{"type":"string","minLength":1},"topic":{"type":["string","null"]},"archived":{"type":"boolean"},"wellKnown":{"type":["string","null"],"description":"`'team'` for the channel every install is opened with, else `null`."},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}},"required":["id","kind","slug","title","topic","archived","wellKnown","createdAt","lastActivityAt"],"description":"The room itself, as it stood when the file was written."},"members":{"type":"array","items":{"$ref":"#/components/schemas/RoomExportMember"},"description":"The roster, oldest membership first."},"scope":{"$ref":"#/components/schemas/RoomExportScope"}},"required":["type","format","version","exportedAt","exportedBy","dorkosVersion","room","members","scope"]},"RoomExportAuthor":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Opaque author id (ULID), exactly as the room stored it."},"kind":{"$ref":"#/components/schemas/AuthorKind"},"displayName":{"type":"string","minLength":1,"description":"What this author was called at the time of export."},"handle":{"type":["string","null"],"description":"What you typed after an `@` to reach them, or `null` when nothing did."},"agentRef":{"type":"string","description":"Agents only: the stable reference derived from the agent directory."}},"required":["id","kind","displayName","handle"],"description":"Who asked for it."},"RoomExportMember":{"type":"object","properties":{"author":{"$ref":"#/components/schemas/RoomExportAuthor"},"responseMode":{"type":"string","enum":["always","engaged","direct-only","mention-only","silent"],"description":"This member's per-room response mode."},"joinedAt":{"type":"string","description":"When they joined."},"joinedSeq":{"type":"integer","minimum":0,"description":"The room's highest seq when they joined — the floor under what they can read."}},"required":["author","responseMode","joinedAt","joinedSeq"]},"RoomExportScope":{"type":"object","properties":{"fromSeq":{"type":"integer","minimum":0,"description":"The exclusive floor: entries strictly above this are in the file. `0` means the room from its first message."},"joinFloorApplied":{"type":"boolean","description":"Whether `fromSeq` is the exporter's own join point. `false` on the operator's export of their own room — the whole-room copy that is the exit path — and `true` for everybody else, who does not retroactively read what was said before they arrived."}},"required":["fromSeq","joinFloorApplied"]},"RoomExportEntry":{"type":"object","properties":{"type":{"type":"string","enum":["entry"]},"seq":{"type":"integer","minimum":1,"description":"The entry's position in the room. Ascending, no gaps."},"id":{"type":"string","minLength":1},"createdAt":{"type":"string"},"kind":{"allOf":[{"$ref":"#/components/schemas/RoomEntryKind"},{"description":"`post` for somebody talking, `notice` for the room's own voice."}]},"author":{"$ref":"#/components/schemas/RoomExportAuthor"},"text":{"type":"string"},"notice":{"allOf":[{"$ref":"#/components/schemas/RoomNoticeCode"},{"description":"Notices only: which of the room's standing lines this is."}]},"subject":{"allOf":[{"$ref":"#/components/schemas/RoomExportAuthor"},{"description":"Who a notice or a moment is ABOUT, when that is not its author."}]},"moment":{"allOf":[{"$ref":"#/components/schemas/RoomMoment"},{"description":"The milestone this post marks, if any."}]},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/RoomExportAuthor"},"description":"Who this message addressed, resolved once at write time and never re-parsed from the text."},"sessionId":{"type":["string","null"],"description":"The agent session that produced this, when one did."},"parentEntryId":{"type":["string","null"],"description":"The entry this answers, for a thread reply."},"threadRootEntryId":{"type":["string","null"],"description":"The head of this entry's thread, or `null` when it is top-level."},"reactions":{"type":"array","items":{"$ref":"#/components/schemas/RoomExportReaction"},"description":"Oldest pill first. `[]` when none."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/RoomAttachment"},"description":"The files posted with this message, by reference. `[]` when none."}},"required":["type","seq","id","createdAt","kind","author","text","mentions","sessionId","parentEntryId","threadRootEntryId","reactions","attachments"]},"RoomExportReaction":{"type":"object","properties":{"emoji":{"$ref":"#/components/schemas/ReactionEmoji"},"firstAt":{"type":"string","description":"When the first of these landed."},"by":{"type":"array","items":{"$ref":"#/components/schemas/RoomExportAuthor"},"description":"Who reacted, in the order they did."}},"required":["emoji","firstAt","by"]},"RoomExportSummary":{"type":"object","properties":{"type":{"type":"string","enum":["summary"]},"entryCount":{"type":"integer","minimum":0,"description":"How many `entry` lines precede this one."},"firstSeq":{"type":["integer","null"],"minimum":1,"description":"The seq of the first entry in the file, or `null` when it holds none."},"lastSeq":{"type":["integer","null"],"minimum":1,"description":"The seq of the last entry in the file, or `null` when it holds none."}},"required":["type","entryCount","firstSeq","lastSeq"]},"PostToRoomResponse":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"entryId":{"type":"string","minLength":1},"seq":{"type":"integer","minimum":1},"triggered":{"type":"array","items":{"$ref":"#/components/schemas/AuthorRef"},"description":"The agents the room ASKED to reply, in roster order — not a promise that any of them did. When the room gathers this message into a batch and that batch closes, it judges it again and can still stop one of these agents: a limit reached (which the room announces as a notice) or, for an agent that was merely overhearing rather than addressed, a decision that it had nothing to add (which is deliberately silent). Neither ever appears in this field. An agent this message NAMED, or the agent on the other side of a direct message, is not subject to the second one. `[]` means the message addressed nobody who could answer, which is the ordinary shape of a message nobody was meant to pick up. An agent already mid-turn is HERE rather than in `skipped`: the room asked it, and it answers when the work in front of it ends."},"skipped":{"type":"array","items":{"$ref":"#/components/schemas/SkippedTrigger"},"description":"The agents this message reached that will not be answering it, each with the rule that stopped it. `[]` is the ordinary case. Nearly every entry here also has a durable notice in the room, and this is the faster path to the same truth rather than a second one. The exception is the one refusal the room deliberately stays quiet about — an agent posting with no turn behind it is stamped at the depth ceiling, so everything it addresses is refused; announcing that in the room would spray a line per room-mate per post, but telling the POSTER, once, in the answer to its own write, is exactly what it needs to hear."}},"required":["accepted","entryId","seq"]},"SkippedTrigger":{"type":"object","properties":{"authorId":{"type":"string","minLength":1,"description":"The agent that will not answer, as a roster author id."},"reason":{"$ref":"#/components/schemas/RoomTriggerSkipReason"}},"required":["authorId","reason"]},"RoomTriggerSkipReason":{"type":"string","enum":["depth","repeat","gone"],"description":"Which rule stopped it. `depth` — this back-and-forth has run as many automatic replies as the room allows. `repeat` — this agent has already taken its share of turns in this exchange. `gone` — its directory no longer holds the agent it was added as, so it can take no turn at all."},"PostToRoomRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000},"sessionId":{"type":"string","minLength":1,"description":"The session that produced this post, when one did."},"attachmentIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"Ids from POST /api/rooms/:id/attachments, in the order they should render. Yours, from this room, and not already posted."}},"required":["text"]},"RoomAttachmentUploadResponse":{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/RoomAttachment"}}},"required":["attachments"]},"ToggleReactionResponse":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"entryId":{"type":"string","minLength":1},"emoji":{"$ref":"#/components/schemas/ReactionEmoji"},"reacted":{"type":"boolean","description":"The state your pill is in NOW: true when this call added the reaction, false when it took one back."},"frequents":{"type":"array","items":{"type":"string"},"description":"Your quick row, recomputed with this reaction counted. Returned so the capsule stays current without a second request."}},"required":["accepted","entryId","emoji","reacted","frequents"]},"ToggleReactionRequest":{"type":"object","properties":{"emoji":{"$ref":"#/components/schemas/ReactionEmoji"},"on":{"type":"boolean","description":"The state to land in: `true` puts the reaction there, `false` takes it away, and both are safe to send twice. Omit to flip whatever is there, which is what a click means. Sending `true` for a reaction you already have does NOT restamp it, so the pill keeps its place in a row ordered by first appearance."}},"required":["emoji"]},"AddRoomMemberRequest":{"type":"object","properties":{"authorId":{"type":"string","minLength":1},"agentPath":{"type":"string","minLength":1,"description":"Add an agent by its directory, minting the author row if this is its first room."},"responseMode":{"type":"string","enum":["always","engaged","direct-only","mention-only","silent"],"description":"Omit to seed from the room kind: the agent manifest for a DM, \"engaged\" for a channel."}}},"UpdateMembershipRequest":{"type":"object","properties":{"responseMode":{"type":"string","enum":["always","engaged","direct-only","mention-only","silent"]}},"required":["responseMode"]},"SetAuthorHandleRequest":{"type":"object","properties":{"handle":{"type":"string","maxLength":64,"description":"The new handle, without its `@`. Empty clears it. Refused with INVALID_HANDLE, HANDLE_TAKEN or HANDLE_RESERVED."}},"required":["handle"]},"PostThreadReplyRequest":{"type":"object","properties":{"rootEntryId":{"type":"string","minLength":1,"description":"The entry this reply hangs off, in this same room. Refused with NESTED_THREAD when it is itself a reply — one level deep is a service policy, not a shape the schema decided."},"text":{"type":"string","minLength":1,"maxLength":100000},"sessionId":{"type":"string","minLength":1,"description":"The session that produced this reply, when one did."},"attachmentIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"Ids from POST /api/rooms/:id/attachments, in the order they should render. Yours, from this room, and not already posted."}},"required":["rootEntryId","text"]},"HaltRoomResponse":{"type":"object","properties":{"stopped":{"type":"integer","minimum":0}},"required":["stopped"]},"PromoteHoldResponse":{"type":"object","properties":{"promoted":{"type":"boolean"}},"required":["promoted"]},"RoomRepo":{"type":"object","properties":{"roomId":{"type":"string"},"mode":{"type":"string","enum":["owned"],"description":"Always 'owned'; linked repos are reserved and refused."},"createdAt":{"type":"string"},"createdBy":{"type":"string","description":"The author id of the operator who enabled it."},"defaultBranch":{"type":"string","enum":["main"]},"caps":{"type":"object","properties":{"maxFileBytes":{"type":"integer"},"maxRepoBytes":{"type":"integer"},"maxRoomMdBytes":{"type":"integer"}},"required":["maxFileBytes","maxRepoBytes","maxRoomMdBytes"]},"lastMergeSeq":{"type":["integer","null"],"description":"The room entry seq of the last merge, or null when nothing has merged yet."}},"required":["roomId","mode","createdAt","createdBy","defaultBranch","caps","lastMergeSeq"]},"RoomRepoStatus":{"type":"object","properties":{"mainCommit":{"type":"string"},"mainCommittedAt":{"type":["string","null"]},"main":{"$ref":"#/components/schemas/RoomMainStatus"},"branches":{"type":"array","items":{"$ref":"#/components/schemas/RoomBranchStatus"}},"strandedWorktrees":{"type":"array","items":{"type":"string"},"description":"Working copies holding work `main` has not got, including ones no current member maps to."},"size":{"type":"object","properties":{"usedBytes":{"type":"integer","minimum":0},"maxRepoBytes":{"type":"integer","minimum":0},"maxFileBytes":{"type":"integer","minimum":0}},"required":["usedBytes","maxRepoBytes","maxFileBytes"]}},"required":["mainCommit","mainCommittedAt","main","branches","strandedWorktrees","size"]},"RoomMainStatus":{"type":"object","properties":{"branch":{"type":["string","null"],"description":"The branch the room’s own copy is on."},"dirty":{"type":"boolean","description":"Whether merges and saves are paused because something outside DorkOS wrote in the room’s own copy."},"strays":{"type":"array","items":{"$ref":"#/components/schemas/RoomStrayChange"}},"strayCount":{"type":"integer","minimum":0,"description":"How many uncommitted changes there are in total."}},"required":["branch","dirty","strays","strayCount"]},"RoomStrayChange":{"type":"object","properties":{"path":{"type":"string","description":"The file that is different, relative to the room’s own copy."},"kind":{"type":"string","enum":["added","modified","deleted","untracked"],"description":"What happened to it: added, modified, deleted, or never tracked at all."},"renamedFrom":{"type":"string","description":"Where the file was before it was renamed, when that is what happened."}},"required":["path","kind"]},"RoomBranchStatus":{"type":"object","properties":{"slug":{"type":"string","description":"The working copy’s directory name, and the tail of the branch."},"branch":{"type":"string"},"agent":{"type":"string","description":"The agent’s display name, sanitized."},"authorId":{"type":"string","description":"The agent whose branch this is, by the same author id the roster and the room’s entries carry — so a client can join this row to a member without learning where that agent lives on disk."},"mine":{"type":"boolean","description":"Whether this row is the caller’s own branch."},"hasWorktree":{"type":"boolean","description":"Whether the working copy is on disk right now."},"ahead":{"type":"integer","minimum":0,"description":"Commits the branch holds that `main` does not."},"behind":{"type":"integer","minimum":0,"description":"Commits `main` holds that the branch does not."},"dirty":{"type":"boolean","description":"Whether the working copy has changes nobody committed."},"stranded":{"type":"boolean","description":"Work `main` has not got — `dirty || ahead > 0`. Drives the explorer’s badge."}},"required":["slug","branch","agent","authorId","mine","hasWorktree","ahead","behind","dirty","stranded"]},"RoomMergeResult":{"type":"object","properties":{"branch":{"type":"string"},"commit":{"type":"string","description":"The merge commit now on the room’s `main`."},"files":{"type":"integer"},"insertions":{"type":"integer"},"deletions":{"type":"integer"},"seq":{"type":"integer","description":"The `seq` of the room entry announcing the merge."}},"required":["branch","commit","files","insertions","deletions","seq"]},"MergeRoomRepoRequest":{"type":"object","properties":{"summary":{"type":"string","minLength":1,"maxLength":200,"description":"What the work does, in one line. It becomes the merge commit’s subject and the sentence the room sees."},"worktree":{"type":"string","minLength":1,"description":"Which working copy to merge, by the slug `room_repo_status` reports. Owner-only; omit it to merge your own."}},"required":["summary"]},"CanvasDocumentListResponse":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/CanvasDocument"}}},"required":["documents"]},"OpenCanvasDocumentRequest":{"type":"object","properties":{"content":{"allOf":[{"$ref":"#/components/schemas/UiCanvasContent"},{"description":"What to show. One of the fourteen canvas shapes."}]},"pinned":{"type":"boolean","description":"Pin it, so it sorts first and is never dropped to make room."}},"required":["content"]},"UpdateCanvasDocumentRequest":{"type":"object","properties":{"content":{"allOf":[{"$ref":"#/components/schemas/UiCanvasContent"},{"description":"Replace what the document shows."}]},"pinned":{"type":"boolean","description":"Pin it, or unpin it."},"activate":{"type":"boolean","description":"Move it to the front of the list. It changes the ORDER and nobody’s open tab — a shared canvas does not steal anyone’s view."}}},"CanvasEditingResponse":{"type":"object","properties":{"editingBy":{"type":["string","null"]},"expiresAt":{"type":["string","null"]}},"required":["editingBy","expiresAt"]},"CanvasEditingRequest":{"type":"object","properties":{"editing":{"type":"boolean"}},"required":["editing"]},"CanvasThreadResponse":{"type":"object","properties":{"threadRootEntryId":{"type":"string","minLength":1,"description":"The entry heading the document’s discussion."},"created":{"type":"boolean","description":"True when this call started the thread; false when it was already there."}},"required":["threadRootEntryId","created"]},"FollowRoomMemberRequest":{"type":"object","properties":{"memberId":{"type":"string","minLength":1,"description":"The person to follow. People only — an agent has no view to share."}},"required":["memberId"]},"PublishRoomViewResponse":{"type":"object","properties":{"followed":{"type":"boolean","description":"True when somebody is following you and the position went out. False means stop sending."}},"required":["followed"]},"PublishRoomViewRequest":{"type":"object","properties":{"documentId":{"type":"string","minLength":1},"url":{"type":"string"},"scrollY":{"type":"integer","minimum":0}},"required":["documentId"]},"CanvasViewingRequest":{"type":"object","properties":{"documentId":{"type":["string","null"],"minLength":1}},"required":["documentId"]},"RoomSnapshot":{"type":"object","properties":{"room":{"$ref":"#/components/schemas/RoomWithRoster"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/RoomEntry"}},"cursor":{"type":"integer","minimum":0},"canvas":{"type":"array","items":{"$ref":"#/components/schemas/CanvasDocument"}}},"required":["room","entries","cursor"]},"RoomEntryEvent":{"type":"object","properties":{"type":{"type":"string","enum":["entry"]},"seq":{"type":"integer","minimum":1},"entry":{"$ref":"#/components/schemas/RoomEntry"}},"required":["type","seq","entry"]},"RoomSignalEvent":{"type":"object","properties":{"type":{"type":"string","enum":["signal"]},"signal":{"$ref":"#/components/schemas/SignalType"},"authorId":{"type":"string","minLength":1},"at":{"type":"string"},"state":{"$ref":"#/components/schemas/RoomPresenceState"},"entryId":{"type":"string"},"since":{"type":"string"},"activity":{"$ref":"#/components/schemas/SessionActivity"},"heldBehind":{"$ref":"#/components/schemas/RoomHeldBehind"},"outcome":{"type":"string","enum":["answered","silent"]},"view":{"$ref":"#/components/schemas/RoomSignalView"},"follows":{"type":["string","null"],"minLength":1},"documentId":{"type":"string"}},"required":["type","signal","authorId","at"]},"SignalType":{"type":"string","enum":["typing","presence","read_receipt","delivery_receipt","progress","backpressure"]},"RoomPresenceState":{"type":"string","enum":["working","working_late","held","done"]},"RoomHeldBehind":{"type":"object","properties":{"roomId":{"type":"string","minLength":1,"description":"The room whose turn is in the way. An id and nothing else: the reader resolves it against the rooms they can already see, and a reader who cannot see it reads \"another conversation\"."},"othersWaiting":{"type":"boolean","description":"This agent is holding a message in at least one OTHER conversation too. A boolean, never a count or a list — it exists only to decide whether \"Answer here first\" would do anything."}},"required":["roomId","othersWaiting"]},"RoomSignalView":{"type":"object","properties":{"documentId":{"type":"string","minLength":1},"url":{"type":"string"},"scrollY":{"type":"integer","minimum":0}},"required":["documentId"]},"RoomReactionEvent":{"type":"object","properties":{"type":{"type":"string","enum":["reaction"]},"entryId":{"type":"string","minLength":1,"description":"The entry in this room whose reactions changed."},"reactions":{"type":"array","items":{"$ref":"#/components/schemas/RoomEntryReaction"},"description":"The entry's COMPLETE reaction set now, not a delta — an empty array means the last pill was taken back."}},"required":["type","entryId","reactions"]},"RoomCanvasEvent":{"type":"object","properties":{"type":{"type":"string","enum":["canvas"]},"documentId":{"type":"string","minLength":1},"document":{"$ref":"#/components/schemas/CanvasDocument"},"closed":{"type":"boolean"},"change":{"type":"string","enum":["opened","updated","activated","pinned"]}},"required":["type","documentId"]},"ReadCursor":{"type":"object","properties":{"userId":{"type":"string"},"threadKind":{"$ref":"#/components/schemas/ReadCursorThreadKind"},"threadId":{"type":"string"},"lastReadSeq":{"type":"integer","minimum":0},"updatedAt":{"type":"string"}},"required":["userId","threadKind","threadId","lastReadSeq","updatedAt"]},"ReadCursorThreadKind":{"type":"string","enum":["room","session","inbox"]},"SetReadCursorPositionRequest":{"type":"object","properties":{"lastReadSeq":{"type":"integer","minimum":0}},"required":["lastReadSeq"]},"ReadCursorResponse":{"type":"object","properties":{"cursor":{"allOf":[{"$ref":"#/components/schemas/ReadCursor"},{"type":["object","null"]}]}},"required":["cursor"]},"TeamRosterResponse":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/TeamSourceWarning"}}},"required":["members"]},"TeamMember":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/AuthorKind"},"displayName":{"type":"string","minLength":1},"handle":{"type":["string","null"]},"emoji":{"type":"string"},"color":{"type":"string"},"imageUrl":{"type":"string"},"isSelf":{"type":"boolean"},"ownerId":{"type":["string","null"]},"origin":{"$ref":"#/components/schemas/AuthorOrigin"},"agent":{"$ref":"#/components/schemas/TeamAgentFacts"},"person":{"$ref":"#/components/schemas/TeamPersonFacts"}},"required":["id","kind","displayName","handle","isSelf","ownerId","origin"]},"TeamAgentFacts":{"type":"object","properties":{"manifestId":{"type":"string","minLength":1},"runtime":{"$ref":"#/components/schemas/AgentRuntime"},"model":{"type":"string"},"healthStatus":{"$ref":"#/components/schemas/AgentHealthStatus"},"recentlyActive":{"type":"boolean"},"namespace":{"type":"string"},"projectPath":{"type":"string"},"activity":{"$ref":"#/components/schemas/TeamAgentActivity"},"isDefault":{"type":"boolean"},"isSystem":{"type":"boolean"},"registeredAt":{"type":"string"}},"required":["manifestId","runtime","healthStatus","recentlyActive","activity","isDefault","isSystem","registeredAt"]},"TeamAgentActivity":{"type":"object","properties":{"working":{"type":["object","null"],"properties":{"roomId":{"type":"string","minLength":1},"roomName":{"type":["string","null"]},"since":{"type":"string"}},"required":["roomId","roomName","since"]},"lastActiveAt":{"type":["string","null"]}},"required":["working","lastActiveAt"]},"TeamPersonFacts":{"type":"object","properties":{"role":{"type":["string","null"]},"email":{"type":"string"},"lastSeenAt":{"type":["string","null"]},"linkedToYou":{"type":"boolean"},"nameSuggestedBy":{"type":["string","null"],"minLength":1}},"required":["role","lastSeenAt"]},"TeamSourceWarning":{"type":"object","properties":{"source":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["source","message"]},"MemberRoomsResponse":{"type":"object","properties":{"rooms":{"type":"array","items":{"$ref":"#/components/schemas/MemberRoom"}}},"required":["rooms"]},"MemberRoom":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"slug":{"type":["string","null"]},"kind":{"$ref":"#/components/schemas/RoomKind"},"memberCount":{"type":"integer","minimum":0}},"required":["id","name","slug","kind","memberCount"]},"SearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SearchSourceWarning"}}},"required":["results","warnings"]},"SearchHit":{"type":"object","properties":{"source":{"type":"string","minLength":1},"container":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1},"containerPath":{"type":["string","null"]},"ordinal":{"type":"integer"},"messageId":{"type":"string","minLength":1},"role":{"$ref":"#/components/schemas/SearchHitRole"},"createdAt":{"type":["string","null"]},"excerpt":{"type":"string"}},"required":["source","container","containerPath","ordinal","role","createdAt","excerpt"]},"SearchHitRole":{"type":"string","enum":["user","assistant"]},"SearchSourceWarning":{"type":"object","properties":{"source":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["source","message"]},"ProfileUpdateResponse":{"type":"object","properties":{"displayName":{"type":"string","minLength":1}},"required":["displayName"]},"ProfileUpdateRequest":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":80}},"required":["displayName"]},"ProfileAvatarResponse":{"type":"object","properties":{"imageUrl":{"type":"string","minLength":1}},"required":["imageUrl"]},"ListNotificationsResponse":{"type":"object","properties":{"notifications":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"nextCursor":{"type":["string","null"]},"unreadCount":{"type":"integer","minimum":0}},"required":["notifications","nextCursor","unreadCount"]},"Notification":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/NotificationKind"},"tier":{"$ref":"#/components/schemas/NotificationTier"},"subject":{"$ref":"#/components/schemas/NotificationSubject"},"agentId":{"type":"string"},"sessionId":{"type":"string"},"roomId":{"type":"string"},"title":{"type":"string","minLength":1},"body":{"type":"string"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/NotificationAction"}},"createdAt":{"type":"string"},"readAt":{"type":"string"},"resolvedAt":{"type":"string"},"outcome":{"$ref":"#/components/schemas/NotificationOutcome"}},"required":["id","kind","tier","subject","title","createdAt"]},"NotificationKind":{"type":"string","enum":["ask.pending","schedule.parked","approval.pending","session.error","turn.completed","run.completed","dm.received","mention.received","agent.note","dead-letter.created","agent.unreachable","signin.required","update.installed","report.daily"]},"NotificationTier":{"type":"string","enum":["blocking","notable","quiet"]},"NotificationSubject":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/NotificationSubjectType"},"id":{"type":"string","minLength":1}},"required":["type","id"]},"NotificationSubjectType":{"type":"string","enum":["session","task","run","room","agent","system"]},"NotificationAction":{"type":"object","properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"style":{"$ref":"#/components/schemas/NotificationActionStyle"}},"required":["id","label","style"]},"NotificationActionStyle":{"type":"string","enum":["primary","danger","neutral"]},"NotificationOutcome":{"type":"string","enum":["answered","expired","cancelled","approved","rejected","cleared"]},"MarkNotificationsReadResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"marked":{"type":"integer","minimum":0},"unreadCount":{"type":"integer","minimum":0}},"required":["ok","marked","unreadCount"]},"VapidPublicKeyResponse":{"type":"object","properties":{"key":{"type":["string","null"]}},"required":["key"]},"ListPushSubscriptionsResponse":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/PushSubscriptionDTO"}}},"required":["subscriptions"]},"PushSubscriptionDTO":{"type":"object","properties":{"id":{"type":"string","minLength":1},"service":{"type":"string"},"createdAt":{"type":"string"},"lastSeenAt":{"type":"string"}},"required":["id","service","createdAt","lastSeenAt"]},"RegisterPushSubscriptionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"subscription":{"$ref":"#/components/schemas/PushSubscriptionDTO"}},"required":["ok","subscription"]},"RegisterPushSubscriptionRequest":{"type":"object","properties":{"endpoint":{"type":"string","format":"uri"},"keys":{"$ref":"#/components/schemas/PushSubscriptionKeys"}},"required":["endpoint","keys"]},"PushSubscriptionKeys":{"type":"object","properties":{"p256dh":{"type":"string","minLength":1},"auth":{"type":"string","minLength":1}},"required":["p256dh","auth"]},"DeletePushSubscriptionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"removed":{"type":"integer","minimum":0}},"required":["ok","removed"]},"WorktreeScanResult":{"type":"object","properties":{"root":{"type":"string"},"worktrees":{"type":"array","items":{"$ref":"#/components/schemas/WorktreeScanEntry"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/WorktreeScanWarning"}}},"required":["root","worktrees","warnings"]},"WorktreeScanEntry":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"},"project":{"type":"string"},"repoPath":{"type":["string","null"]},"branch":{"type":["string","null"]},"changedFiles":{"type":["integer","null"]},"ahead":{"type":["integer","null"]},"behind":{"type":["integer","null"]},"upstreamGone":{"type":"boolean"},"lastCommitAt":{"type":["string","null"]},"readable":{"type":"boolean"}},"required":["path","name","project","repoPath","branch","changedFiles","ahead","behind","upstreamGone","lastCommitAt","readable"]},"WorktreeScanWarning":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]},"ActorType":{"type":"string","enum":["user","agent","system","tasks"]},"ManagedMcpServerView":{"allOf":[{"$ref":"#/components/schemas/ManagedMcpServer"},{"type":"object","properties":{"authStatus":{"type":"string","enum":["connected","needs-auth"]},"authClientOrigin":{"type":"string","enum":["dcr","manual"]}}}]}},"parameters":{}},"paths":{"/api/connectors/accessible/subscriptions":{"get":{"tags":["Connections"],"summary":"List notifications one agent is allowed to receive","description":"Requires a verified API key and an explicit owned agent. Read-only; operation grants do not imply receive access. No event content or private service references are returned.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"name":"agentId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Current agent-scoped receive grants.","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"maxLength":256},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"connectionId":{"type":"string","minLength":1},"definitionId":{"type":"string","minLength":1,"maxLength":256},"eventType":{"type":"string","minLength":1,"maxLength":256},"displayName":{"type":"string","minLength":1,"maxLength":512},"deliveryMode":{"type":"string","enum":["webhook","polling","unknown"]},"expectedCadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"agentId":{"type":"string","minLength":1,"maxLength":256},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","room","channel"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"filter":{"type":"object","additionalProperties":{}},"scopeVersion":{"type":"integer","exclusiveMinimum":0},"state":{"type":"string","enum":["active","unavailable"]},"toolkit":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":512}},"required":["id","connectionId","definitionId","eventType","displayName","deliveryMode","expectedCadenceSeconds","agentId","destination","filter","scopeVersion","state","toolkit","label"],"additionalProperties":false},"maxItems":100},"nextCursor":{"type":"string","minLength":1,"maxLength":1024}},"required":["agentId","subscriptions"],"additionalProperties":false}}}},"400":{"description":"An agent or cursor is invalid."},"401":{"description":"The API key is missing or no longer active."},"403":{"description":"Agent runtime credentials cannot act as a program API key."},"404":{"description":"The agent is not owned by this API key user."}}}},"/api/connectors/connections/{connectionId}/events/definitions":{"get":{"tags":["Connections"],"summary":"List notification types for an owned connection","description":"Owner-only. Setup mode and configured state do not imply that event delivery is ready.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"},{"schema":{"type":"string","maxLength":512},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Current owner-scoped notification metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"definitions":{"type":"array","items":{"type":"object","properties":{"eventType":{"type":"string","minLength":1,"maxLength":256},"displayName":{"type":"string","minLength":1,"maxLength":512},"toolkit":{"type":"string","minLength":1,"maxLength":128},"toolkitVersion":{"type":"string","minLength":1,"maxLength":128},"definitionHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"filterSchema":{"type":"object","additionalProperties":{}},"payloadSchema":{"type":"object","additionalProperties":{}},"deliveryMode":{"type":"string","enum":["webhook","polling","unknown"]},"expectedCadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["eventType","displayName","toolkit","toolkitVersion","definitionHash","filterSchema","payloadSchema","deliveryMode","expectedCadenceSeconds","id"],"additionalProperties":false},"maxItems":100},"nextCursor":{"type":"string","minLength":1,"maxLength":512}},"required":["definitions"],"additionalProperties":false}}}},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}}},"/api/connectors/connections/{connectionId}/events/subscriptions":{"get":{"tags":["Connections"],"summary":"List exact notification destinations and consent state","description":"Owner-only. Setup mode and configured state do not imply that event delivery is ready.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"},{"schema":{"type":"string","maxLength":512},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Current owner-scoped notification metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"connectionId":{"type":"string","minLength":1},"definitionId":{"type":"string","minLength":1,"maxLength":256},"eventType":{"type":"string","minLength":1,"maxLength":256},"displayName":{"type":"string","minLength":1,"maxLength":512},"deliveryMode":{"type":"string","enum":["webhook","polling","unknown"]},"expectedCadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"agentId":{"type":"string","minLength":1,"maxLength":256},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","room","channel"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"filter":{"type":"object","additionalProperties":{}},"scopeVersion":{"type":"integer","exclusiveMinimum":0},"state":{"type":"string","enum":["active","pending","revoked","unavailable"]}},"required":["id","connectionId","definitionId","eventType","displayName","deliveryMode","expectedCadenceSeconds","agentId","destination","filter","scopeVersion","state"],"additionalProperties":false},"maxItems":100},"nextCursor":{"type":"string","minLength":1,"maxLength":256}},"required":["subscriptions"],"additionalProperties":false}}}},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}},"post":{"tags":["Connections"],"summary":"Approve an exact notification destination","description":"The requestId identifies one immutable explicit owner decision. Changing its scope conflicts; revocation cannot be undone by replay.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definitionId":{"type":"string","minLength":1,"maxLength":256},"filter":{"type":"object","additionalProperties":{}},"agentId":{"type":"string","minLength":1,"maxLength":256},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","room","channel"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"manageExistingTrigger":{"type":"boolean","default":false}},"required":["definitionId","filter","agentId","destination","requestId"],"additionalProperties":false}}}},"responses":{"201":{"description":"The exact receive consent is active.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"connectionId":{"type":"string","minLength":1},"definitionId":{"type":"string","minLength":1,"maxLength":256},"eventType":{"type":"string","minLength":1,"maxLength":256},"displayName":{"type":"string","minLength":1,"maxLength":512},"deliveryMode":{"type":"string","enum":["webhook","polling","unknown"]},"expectedCadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"agentId":{"type":"string","minLength":1,"maxLength":256},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","room","channel"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"filter":{"type":"object","additionalProperties":{}},"scopeVersion":{"type":"integer","exclusiveMinimum":0},"state":{"type":"string","enum":["active","pending","revoked","unavailable"]}},"required":["id","connectionId","definitionId","eventType","displayName","deliveryMode","expectedCadenceSeconds","agentId","destination","filter","scopeVersion","state"],"additionalProperties":false}}}},"202":{"description":"Consent is recorded; remote acknowledgement is pending.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"connectionId":{"type":"string","minLength":1},"definitionId":{"type":"string","minLength":1,"maxLength":256},"eventType":{"type":"string","minLength":1,"maxLength":256},"displayName":{"type":"string","minLength":1,"maxLength":512},"deliveryMode":{"type":"string","enum":["webhook","polling","unknown"]},"expectedCadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"agentId":{"type":"string","minLength":1,"maxLength":256},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","room","channel"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"filter":{"type":"object","additionalProperties":{}},"scopeVersion":{"type":"integer","exclusiveMinimum":0},"state":{"type":"string","enum":["active","pending","revoked","unavailable"]}},"required":["id","connectionId","definitionId","eventType","displayName","deliveryMode","expectedCadenceSeconds","agentId","destination","filter","scopeVersion","state"],"additionalProperties":false}}}},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"409":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}}},"/api/connectors/connections/{connectionId}/events/source":{"get":{"tags":["Connections"],"summary":"Read notification setup mode without credential material","description":"Owner-only. Setup mode and configured state do not imply that event delivery is ready.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Current owner-scoped notification metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"setupMode":{"type":"string","enum":["managed","byo_webhook","unavailable"]},"configured":{"type":"boolean"},"endpoint":{"type":["string","null"],"format":"uri"},"reason":{"type":["string","null"],"maxLength":512}},"required":["setupMode","configured","endpoint","reason"],"additionalProperties":false}}}},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}},"put":{"tags":["Connections"],"summary":"Configure a write-only webhook signing secret","description":"Available only when setupMode is byo_webhook. The secret never appears in a response. Payload encryption uses a separately managed key.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhookSecret":{"type":"string","minLength":16,"maxLength":4096},"publicOrigin":{"type":"string","format":"uri"}},"required":["webhookSecret","publicOrigin"],"additionalProperties":false}}}},"responses":{"200":{"description":"Local signing setup was saved; this does not prove event delivery.","content":{"application/json":{"schema":{"type":"object","properties":{"setupMode":{"type":"string","enum":["managed","byo_webhook","unavailable"]},"configured":{"type":"boolean"},"endpoint":{"type":["string","null"],"format":"uri"},"reason":{"type":["string","null"],"maxLength":512}},"required":["setupMode","configured","endpoint","reason"],"additionalProperties":false}}}},"400":{"description":"Notifications are unavailable or the owner decision changed."},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}}},"/api/connectors/connections/{connectionId}/events/subscriptions/{subscriptionId}":{"delete":{"tags":["Connections"],"summary":"Permanently revoke this notification generation","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"subscriptionId","in":"path"}],"responses":{"204":{"description":"Local receive authority is closed; upstream cleanup may still be pending."},"403":{"description":"Notifications are unavailable or the owner decision changed."},"404":{"description":"Notifications are unavailable or the owner decision changed."},"503":{"description":"Notifications are unavailable or the owner decision changed."}}}},"/api/health":{"get":{"tags":["Health"],"summary":"Health check","responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/health/deep":{"get":{"tags":["Health"],"summary":"Deep health checks","description":"The setup checks that need a running server: room-to-session bindings with no transcript, quarantined relay access rules, unreadable chat-connection entries, relay bindings pointing at a missing adapter or agent, and duplicate agent ids. Always answers 200 — a failing check is data, not an HTTP error. Results are content-free (counts and plain sentences only) and share the `CheckResult` shape `dorkos doctor` renders; `dorkos doctor --deep` merges them into its checklist.","responses":{"200":{"description":"One check result per deep check, in a fixed order","content":{"application/json":{"schema":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail","info"]},"detail":{"type":"string"},"fix":{"type":"string"}},"required":["label","status"]}}},"required":["checks"]}}}}}}},"/api/sessions":{"get":{"tags":["Sessions"],"summary":"List all sessions","description":"Aggregates sessions across every registered runtime (ADR-0310). Runtimes that fail or time out degrade to `warnings[]` entries with partial results.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cwd","in":"query"},{"schema":{"type":"string"},"required":false,"name":"runtime","in":"query"}],"responses":{"200":{"description":"Session list envelope (merged across runtimes, sorted by updatedAt desc)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/pending-interactions":{"get":{"tags":["Sessions"],"summary":"Every prompt waiting on a person","description":"One envelope per prompt any live session is parked on — a tool approval, a question, or an MCP elicitation — with server-authoritative time left and expired entries already dropped. `roomId` is present only for a session bound to a room. This is the seed a window reads on mount; after that the `interaction_pending` and `interaction_resolved` events on `/api/events` keep it current, so it is never polled. Bounded to live sessions: a projector lives until its session is evicted or the server restarts, so this answers for the recent fleet and not for all history. The list is SCOPED TO THE CALLER: a prompt is only ever listed to somebody who could act on it, so a caller presenting `X-DorkOS-Agent` receives an empty array — and an empty array, never a `403`, because a refusal would itself say that prompts exist.","responses":{"200":{"description":"Every pending prompt, with the room each belongs to when it has one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingInteractionsResponse"}}}}}}},"/api/sessions/recent":{"get":{"tags":["Sessions"],"summary":"List recent sessions across all agents","description":"Fans out session listing across every registered agent (DOR-329), merges by `updatedAt` descending, trims to `limit`, and returns a per-agent latest-activity map plus per-runtime `warnings[]` (ADR-0310).","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Recent sessions envelope with per-agent activity map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentSessionsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/daily-counts":{"get":{"tags":["Sessions"],"summary":"Count sessions started per day across all agents","description":"Counts the sessions started each local day across every registered agent (DOR-1039), oldest day first. Per-runtime failures degrade to `warnings[]`, which makes the counts a floor rather than a total (ADR-0310).","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":31,"default":7},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"Machine-wide daily session counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDailyCountsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}":{"get":{"tags":["Sessions"],"summary":"Get session details","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Sessions"],"summary":"Update session settings","description":"$fe","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSessionRequest"}}}},"responses":{"200":{"description":"Updated session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUpdateResponse"}}}},"202":{"description":"Saved, but a stricter permission mode did not reach the reply already in flight — it applies from the next reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUpdateResponse"}}}},"400":{"description":"Validation error, or a permission mode the runtime does not declare","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"428":{"description":"A mode that never stops to ask was requested without an acknowledgement (`AUTONOMY_ACK_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/messages":{"get":{"tags":["Sessions"],"summary":"Get message history","description":"`cwd` is optional (DOR-1322): the server first tries the runtime's own live binding for the session, then falls back to its default project directory — but only after VERIFYING the session actually lives there, never on the unchecked assumption that it does. Pass `cwd` explicitly for a session the server has never loaded this process — a cold read straight from the SDK transcript. A session that cannot be placed either way (no live binding, and not confirmed at the default directory) answers 404 SESSION_CWD_REQUIRED rather than an empty message list, so \"no messages yet\" and \"wrong or missing cwd\" are never the same response.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The session's project directory (boundary-checked). Optional for a session the server can already place; required for a cold session it cannot."},"required":false,"description":"The session's project directory (boundary-checked). Optional for a session the server can already place; required for a cold session it cannot.","name":"cwd","in":"query"}],"responses":{"200":{"description":"Message history","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/HistoryMessage"}}},"required":["messages"]}}}},"404":{"description":"Could not determine this session's working directory (SESSION_CWD_REQUIRED). Retry with an explicit `cwd`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Sessions"],"summary":"Send message (accept-only)","description":"$ff","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"202":{"description":"Message accepted; body carries the canonical session id and the receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/events":{"get":{"tags":["Sessions"],"summary":"Durable session stream (SSE, or WebSocket at the same path)","description":"$100","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Project directory (boundary-checked)."},"required":false,"description":"Project directory (boundary-checked).","name":"cwd","in":"query"},{"schema":{"type":"string","description":"Resume cursor; replay events with seq greater than this. A bare integer that names no server process and no event counter, so it is checked only against the replay window. Safe when it is the cursor of a snapshot just taken on the same connection, which is all DorkOS's own HTTP transport uses it for; a cursor PERSISTED across a reconnect must be the whole `Last-Event-ID`/`resume` frame id, which carries both."},"required":false,"description":"Resume cursor; replay events with seq greater than this. A bare integer that names no server process and no event counter, so it is checked only against the replay window. Safe when it is the cursor of a snapshot just taken on the same connection, which is all DorkOS's own HTTP transport uses it for; a cursor PERSISTED across a reconnect must be the whole `Last-Event-ID`/`resume` frame id, which carries both.","name":"after","in":"query"},{"schema":{"type":"string","description":"Resume token `---`, for WebSocket clients, which cannot set headers. Same meaning as `Last-Event-ID`; takes precedence over `after`."},"required":false,"description":"Resume token `---`, for WebSocket clients, which cannot set headers. Same meaning as `Last-Event-ID`; takes precedence over `after`.","name":"resume","in":"query"},{"schema":{"type":"string","description":"Resume token `---`; replays only the gap. A token from a previous server process (epoch mismatch), from a superseded seq space (generation mismatch), in the older generation-less format, or beyond the replay buffer falls back to a cold snapshot."},"required":false,"description":"Resume token `---`; replays only the gap. A token from a previous server process (epoch mismatch), from a superseded seq space (generation mismatch), in the older generation-less format, or beyond the replay buffer falls back to a cold snapshot.","name":"Last-Event-ID","in":"header"}],"responses":{"200":{"description":"SSE stream. Cold connect: a `snapshot` event then `id:`-framed SessionEvents. Resume connect: replayed-then-live `id:`-framed SessionEvents (no snapshot). A WebSocket upgrade of the same path answers `101` and carries the identical sequence as JSON frames.","content":{"text/event-stream":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SessionSnapshot"},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["text_delta"]},"text":{"type":"string"}},"required":["seq","type","text"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["thinking_delta"]},"text":{"type":"string"}},"required":["seq","type","text"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_call"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"ui":{"$ref":"#/components/schemas/McpAppRef"}},"required":["seq","type","toolCallId","toolName","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_result"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"result":{"type":"string"},"status":{"type":"string","enum":["pending","running","complete","error"]},"ui":{"$ref":"#/components/schemas/McpAppRef"}},"required":["seq","type","toolCallId","toolName","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["tool_progress"]},"toolCallId":{"type":"string"},"content":{"type":"string"}},"required":["seq","type","toolCallId","content"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["approval_required"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"toolName":{"type":"string"},"input":{"type":"string"},"title":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"blockedPath":{"type":"string"},"decisionReason":{"type":"string"},"hasSuggestions":{"type":"boolean"},"alwaysAllowScope":{"$ref":"#/components/schemas/AlwaysAllowScope"}},"required":["seq","type","startedAt","remainingMs","id","toolName","input","hasSuggestions"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["question_prompt"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/QuestionItem"}}},"required":["seq","type","startedAt","remainingMs","id","questions"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["elicitation_prompt"]},"startedAt":{"type":"number"},"remainingMs":{"type":"number"},"timeoutMs":{"type":"number"},"id":{"type":"string"},"serverName":{"type":"string"},"message":{"type":"string"},"mode":{"$ref":"#/components/schemas/ElicitationMode"},"url":{"type":"string"},"elicitationId":{"type":"string"},"requestedSchema":{"type":"object","additionalProperties":{}}},"required":["seq","type","startedAt","remainingMs","id","serverName","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["status_change"]},"status":{"type":"object","properties":{"contextUsage":{"type":["object","null"],"properties":{"totalTokens":{"type":"integer"},"maxTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheCreationTokens":{"type":"integer"}}},"cost":{"type":["number","null"]},"usage":{"$ref":"#/components/schemas/UsageStatus"},"cacheStats":{"$ref":"#/components/schemas/SessionCacheStats"},"model":{"type":["string","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionModeId"},"todoCounts":{"$ref":"#/components/schemas/SessionTodoCounts"},"runningSubagentCount":{"type":"integer","default":0},"lifecycle":{"$ref":"#/components/schemas/SessionLifecycle"},"lastError":{"$ref":"#/components/schemas/ErrorEvent"},"steerable":{"type":"boolean"}}}},"required":["seq","type","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["todo_update"]},"action":{"type":"string","enum":["create","update","snapshot","id_assigned","remove"]},"task":{"$ref":"#/components/schemas/TaskItem"},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/TaskItem"}},"previousId":{"type":"string"}},"required":["seq","type","action","task"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["subagent_update"]},"taskId":{"type":"string"},"status":{"$ref":"#/components/schemas/BackgroundTaskStatus"},"description":{"type":"string"},"toolUses":{"type":"integer"},"lastToolName":{"type":"string"},"summary":{"type":"string"},"ambient":{"type":"boolean"}},"required":["seq","type","taskId","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["hook_update"]},"hookId":{"type":"string"},"status":{"type":"string","enum":["running","success","error","cancelled"]},"hookName":{"type":"string"},"hookEvent":{"type":"string"},"toolCallId":{"type":["string","null"]},"stdout":{"type":"string"},"stderr":{"type":"string"},"exitCode":{"type":"number"}},"required":["seq","type","hookId","status"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["memory_recall"]},"mode":{"type":"string","enum":["select","synthesize"]},"memories":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"scope":{"type":"string","enum":["personal","team"]},"content":{"type":"string"}},"required":["path","scope"]}}},"required":["seq","type","mode","memories"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["image_attachment"]},"attachmentId":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"mediaType":{"type":"string","minLength":1},"size":{"type":"integer","minimum":0},"alt":{"type":"string"}},"required":["seq","type","attachmentId","url","mediaType","size"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["compact_boundary"]},"trigger":{"type":"string","enum":["manual","auto"]},"preTokens":{"type":"integer"},"postTokens":{"type":"integer"},"durationMs":{"type":"integer"}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["permission_denied"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"reasonType":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"agentId":{"type":"string"}},"required":["seq","type","toolCallId","toolName","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["system_status"]},"message":{"type":"string"},"status":{"type":"string"}},"required":["seq","type","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["operation_progress"]},"operation":{"$ref":"#/components/schemas/OperationKind"},"state":{"$ref":"#/components/schemas/OperationState"},"determinate":{"type":"boolean"},"percent":{"type":"number","minimum":0,"maximum":100},"message":{"type":"string"},"error":{"type":"string"}},"required":["seq","type","operation","state","determinate"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["error"]},"message":{"type":"string"},"code":{"type":"string"},"category":{"$ref":"#/components/schemas/ErrorCategory"},"details":{"type":"string"}},"required":["seq","type","message"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["interaction_resolved"]},"id":{"type":"string"},"resolution":{"type":"string","enum":["approved","denied","answered","expired","cancelled"]},"kind":{"type":"string","enum":["approval","question","elicitation"]},"at":{"type":"number"},"startedAt":{"type":"number"},"reasonGiven":{"type":"boolean"},"resolvedBy":{"type":"string"}},"required":["seq","type","id"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["capability_approval_required"]},"startedAt":{"type":"number"},"capMs":{"type":"number"},"approval":{"$ref":"#/components/schemas/PendingApproval"}},"required":["seq","type","startedAt","capMs","approval"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["capability_approval_resolved"]},"approvalId":{"type":"string"},"outcome":{"type":"string","enum":["granted","denied","expired","timeout"]}},"required":["seq","type","approvalId","outcome"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["mcp_signin_required"]},"serverName":{"type":"string"},"agentId":{"type":"string"},"flowId":{"type":"string"},"authorizeUrl":{"type":"string"},"disclosure":{"type":"string"}},"required":["seq","type","serverName","agentId","flowId","authorizeUrl","disclosure"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["mcp_signin_resolved"]},"flowId":{"type":"string"},"outcome":{"type":"string","enum":["connected","failed"]},"toolCount":{"type":"integer","minimum":0}},"required":["seq","type","flowId","outcome"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_start"]},"userMessage":{"type":"string"},"origin":{"type":"string","enum":["user","runtime"]}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_end"]},"terminalReason":{"$ref":"#/components/schemas/TerminalReason"},"stopWasRequested":{"type":"boolean"}},"required":["seq","type"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["turn_input"]},"content":{"type":"string"},"disposition":{"type":"string","enum":["steer"]},"messageId":{"type":"string"}},"required":["seq","type","content","disposition","messageId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["ui_command"]},"command":{"$ref":"#/components/schemas/UiCommand"},"applied":{"type":"object","properties":{"documentId":{"type":"string","minLength":1},"rev":{"type":"integer","minimum":0}},"required":["documentId","rev"]}},"required":["seq","type","command"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["canvas"]},"documentId":{"type":"string","minLength":1},"document":{"$ref":"#/components/schemas/CanvasDocument"},"closed":{"type":"boolean"},"change":{"type":"string","enum":["opened","updated","activated","pinned"]}},"required":["seq","type","documentId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_capture_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"}},"required":["seq","type","requestId"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_action_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"},"command":{"$ref":"#/components/schemas/BrowserActCommand"},"capture":{"type":"boolean"}},"required":["seq","type","requestId","targetClientId","documentId","command"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["devtools_recording_request"]},"requestId":{"type":"string"},"targetClientId":{"type":"string"},"documentId":{"type":"string"},"action":{"type":"string","enum":["start","stop"]},"recordingId":{"type":"string"},"bounds":{"type":"object","properties":{"longEdgePx":{"type":"integer","exclusiveMinimum":0},"frameMs":{"type":"integer","exclusiveMinimum":0},"maxBytes":{"type":"integer","exclusiveMinimum":0}},"required":["longEdgePx","frameMs","maxBytes"]}},"required":["seq","type","requestId","targetClientId","documentId","action","recordingId","bounds"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["queue_update"]},"queue":{"type":"array","items":{"$ref":"#/components/schemas/QueuedMessage"}},"outcome":{"$ref":"#/components/schemas/MessageDeliveryOutcome"}},"required":["seq","type","queue"]},{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"type":{"type":"string","enum":["context_staged"]},"content":{"type":"string"},"messageId":{"type":"string"}},"required":["seq","type","content","messageId"]}],"description":"A SessionSnapshot (cold connect) followed by SessionEvent frames."}}}},"400":{"description":"Invalid session ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/tasks":{"get":{"tags":["Sessions"],"summary":"Get task state from session transcript","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Task list","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/TaskItem"}}},"required":["tasks"]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/queue":{"get":{"tags":["Sessions"],"summary":"List the messages waiting on a session","description":"The messages accepted for this session that have not run yet, head first. The same list rides the session snapshot on `GET /api/sessions/{id}/events`, so a DorkOS client never needs this route; it is here for integrations and debugging.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The session's queue, in dispatch order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionQueueResponse"}}}},"400":{"description":"Invalid session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/queue/{messageId}":{"patch":{"tags":["Sessions"],"summary":"Edit or move a waiting message","description":"Changes a waiting message's words, its place in the queue, or both. A move names another message to land before or after rather than an index, because an index means something different to every window the moment anybody else edits the queue. The queue belongs to the SESSION: any client may edit any message on it, whichever client enqueued it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"messageId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQueuedMessageRequest"}}}},"responses":{"200":{"description":"The edited message and the queue around it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQueuedMessageResponse"}}}},"400":{"description":"Invalid ids, or a body that asks for no change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such message on this queue (dispatched, removed, or never here)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Sessions"],"summary":"Remove a waiting message","description":"Takes a waiting message off the queue; it will not run. Any client may remove any message on the session's queue.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"messageId","in":"path"}],"responses":{"200":{"description":"The queue as it now stands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionQueueResponse"}}}},"400":{"description":"Invalid ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such message on this queue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/command-intents/{intent}":{"post":{"tags":["Sessions"],"summary":"Trigger a runtime-fulfilled command intent (trigger-only)","description":"TRIGGERS a RUNTIME-fulfilled command intent (currently `compact`) and returns immediately (DOR-109, ADR-0273/ADR-0264). The runtime expands the neutral intent into its native mechanism (Claude: bare `/compact`; OpenCode: `session.summarize`), and the outcome — a compaction — is delivered solely on the durable `GET /api/sessions/{id}/events` stream (e.g. a `compact_boundary`), NOT in this response. The client-native intents (`clear`, `context`) are handled entirely client-side and never reach this route. Capability-gated: a runtime that does not support the intent (e.g. Codex) returns `422` and the adapter is never called — never a silent no-op. Unlike the message trigger (which queues instead), this route still answers `409` SESSION_LOCKED when a turn is already running: a command intent is not a person's words waiting to be said, so it is refused rather than queued.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["compact"]},"required":true,"name":"intent","in":"path"}],"requestBody":{"description":"Optional trailing instructions the user typed after the intent token (e.g. `/compact focus on the API changes`). Forwarded to runtimes whose native mechanism accepts guidance (claude-code); ignored by those whose mechanism takes none (opencode).","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"instructions":{"type":"string"}}}}}},"responses":{"202":{"description":"Intent accepted and started; body carries the session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTriggerResponse"}}}},"400":{"description":"Invalid session id or malformed request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Session locked by another client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown intent, or the session runtime does not support it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/approve":{"post":{"tags":["Sessions"],"summary":"Approve pending tool call","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRequest"}}}},"responses":{"200":{"description":"Approved","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No pending approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/deny":{"post":{"tags":["Sessions"],"summary":"Deny pending tool call","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRequest"}}}},"responses":{"200":{"description":"Denied","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No pending approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/submit-answers":{"post":{"tags":["Sessions"],"summary":"Submit answers for AskUserQuestion","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitAnswersRequest"}}}},"responses":{"200":{"description":"Answers submitted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No pending question","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/ui-action":{"post":{"tags":["Sessions"],"summary":"Dispatch a generative-UI widget agent action","description":"A click on an `agent`-kind widget action. Injects a structured `` block as the next user turn (trigger-only, 202; the turn streams over /events). Unlike the message trigger (which queues instead), this route answers 409 SESSION_LOCKED while the agent is still PRODUCING a turn: a widget click is not a person's words waiting to be said, so it is refused rather than queued. A click that lands after the turn ended is accepted, even if the runtime is still closing that turn's stream behind it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UiActionRequest"}}}},"responses":{"202":{"description":"Action accepted; the turn is delivered over /events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTriggerResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Session is running a turn (locked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/mcp-app/resource":{"post":{"tags":["Sessions"],"summary":"Read a ui:// MCP App resource","description":"Reads a `ui://` MCP App resource (SEP-1865) for client rendering. The server opens its own short-lived MCP client using connection config it captured internally — the stdio/http config never travels to the client. Enforces the `ui://` scheme, `text/html` mime, and that the server belongs to the session's MCP set.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpAppResourceRequest"}}}},"responses":{"200":{"description":"The resource body plus its sandbox metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpAppResourceResponse"}}}},"400":{"description":"Validation error or non-ui:// URI","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session, server, or captured config not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Resource is not renderable HTML","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream MCP read failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/models":{"get":{"tags":["Models"],"summary":"List available Claude models","description":"Returns models available to the user. Serves SDK-reported models if cached, otherwise returns defaults.","responses":{"200":{"description":"List of available models","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/ModelOption"}}},"required":["models"]}}}}}}},"/api/capabilities":{"get":{"tags":["Capabilities"],"summary":"Get runtime capabilities","description":"Returns capabilities for all registered runtimes, keyed by type string, along with the default runtime type.","responses":{"200":{"description":"Runtime capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string","description":"Runtime identifier, e.g. claude-code"},"supportsToolApproval":{"type":"boolean"},"supportsCostTracking":{"type":"boolean"},"supportsResume":{"type":"boolean"},"supportsMcp":{"type":"boolean"},"supportsManagedMcpServers":{"type":"boolean","description":"Whether DorkOS can inject the agent’s own managed MCP servers into its sessions (distinct from the in-process DorkOS tool server, `supportsMcp`)."},"supportsQuestionPrompt":{"type":"boolean"},"supportsPlugins":{"type":"boolean","description":"Whether this runtime can load plugins."},"permissionModes":{"type":"object","properties":{"supported":{"type":"boolean"},"default":{"type":"string","description":"Mode id used when a session has no stored preference. Always one of `values[].id`. Absent when the runtime declares none."},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Runtime-specific permission-mode identifier."},"label":{"type":"string","description":"Display label for UI pickers."},"description":{"type":"string","description":"Optional helper copy shown beneath the label in rich pickers."},"stop":{"type":"string","enum":["ask","act","autonomy"],"description":"Which of the three fixed dial positions this mode belongs to: `ask` (stop before changing anything), `act` (work on, stop for the risky parts), `autonomy` (never stop). Clients render the position; they never invent a fourth or rename one."},"promise":{"type":"string","description":"One plain sentence about what happens under this mode, shown verbatim as the caption beneath the picker. Product copy — the consequence, not the mechanism."},"asks":{"type":"string","enum":["always","when-risky","never"],"description":"How often this mode stops to ask the person, as the runtime measures its own behavior. Where it disagrees with `stop`’s canonical expectation (`ask`→always, `act`→when-risky, `autonomy`→never) the surface says so out loud rather than hiding the difference."},"reach":{"type":"string","enum":["read","edit","workspace","everything"],"description":"How far this mode’s actions can reach, whether or not it asks first: `read` (nothing changes), `edit` (project files), `workspace` (files and commands inside the project), `everything` (no sandbox — the whole machine and the network). With `asks`, decides how loudly a client marks the mode: never-asking plus everything-reaching is the one combination that earns red."},"axis":{"type":"string","enum":["trust","working"],"description":"Which question this mode answers: `trust` (how much the agent may do before it checks with you — the modes the three dial positions select between) or `working` (how it goes about the work, whatever the trust level, e.g. Claude’s `plan`). **Absent means `trust`**, so a runtime that says nothing gets the common answer and keeps its place on the dial. Declare `working` only for a mode that is not a point on the trust axis at all."},"native":{"type":"string","description":"The runtime’s own name for this mode when it differs from `id` — e.g. Codex’s `workspace-write`. Shown in detail views; absent when the id is the native name."}},"required":["id","label","stop","promise","asks","reach"]}}},"required":["supported","values"],"description":"Structured permission-mode capability. `supported: false, values: []` means no picker is shown."},"settings":{"type":"object","properties":{"configSection":{"type":["string","null"],"description":"Key of this runtime’s section under `runtimes.*` in user config (`claudeCode`, `codex`, `opencode`). `null` when the runtime has no config section, in which case it never appears in `executionDefaults.perRuntime`."},"supportsEffort":{"type":"boolean","description":"Whether this runtime takes a reasoning-effort setting at all. Per-model support is a separate, catalog-level fact on `ModelOption.supportsEffort`."},"sections":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"]},"description":"Ordered bespoke settings sections the runtime declares, by renderer kind (`claude-accounts`, `opencode-power-source`). Unknown kinds render nothing."}},"required":["configSection","supportsEffort","sections"],"description":"Static settings declaration: which config section holds this runtime’s defaults, whether it takes effort, and which bespoke sections its settings card renders."},"features":{"type":"object","additionalProperties":{},"description":"Runtime-specific extension point; see ADR 0256."}},"required":["type","supportsToolApproval","supportsCostTracking","supportsResume","supportsMcp","supportsManagedMcpServers","supportsQuestionPrompt","supportsPlugins","permissionModes","settings","features"]}},"defaultRuntime":{"type":"string"}},"required":["capabilities","defaultRuntime"]}}}}}}},"/api/directory":{"get":{"tags":["Directory"],"summary":"Browse directories","description":"Browse directories on the server filesystem. Restricted to the home directory for security.","parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"path","in":"query"},{"schema":{"type":["boolean","null"],"default":false},"required":false,"name":"showHidden","in":"query"}],"responses":{"200":{"description":"Directory listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowseDirectoryResponse"}}}},"400":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied (path outside home directory)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Directory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/directory/default":{"get":{"tags":["Directory"],"summary":"Get default working directory","description":"Returns the server's boundary-resolved default working directory.","responses":{"200":{"description":"Default directory path","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}}}}}}},"/api/workbench/sign":{"post":{"tags":["Workbench"],"summary":"Mint a signed URL for the embedded browser","description":"Mints what the embedded browser needs to load a target, gated by the app-wide session auth. A `serve` request gets a short-lived signed URL into `GET /api/workbench/serve/{token}/{splat}`, after its `cwd` is checked against the boundary. A `proxy` request opens (or reuses) a preview listener for that dev-server port and returns its bootstrap URL — a whole origin of its own, because a dev server served under a path prefix cannot resolve its own root-absolute assets.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchSignRequest"}}}},"responses":{"200":{"description":"Signed URL to load, or a null url with an honest reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchSignResponse"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied: cwd outside directory boundary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/workbench/probe":{"post":{"tags":["Workbench"],"summary":"Probe a loopback port before framing it","description":"Reports whether a loopback port has a server on it, so the embedded browser can explain a dead port instead of framing a blank preview. Gated by the app-wide session auth and loopback-pinned: the body carries a port and nothing else.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchProbeRequest"}}}},"responses":{"200":{"description":"Whether something accepted a connection on that port","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchProbeResponse"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/workbench/serve/{token}/{splat}":{"get":{"tags":["Workbench"],"summary":"Serve a local file signed by /sign","description":"Statically serves a local file from the signed token's `cwd` so relative assets resolve, with the remainder re-confined against `cwd` (a `..`/symlink escape is rejected). Authorized by the signed token, NOT cookie/header auth — the browser frame is opaque-origin and credential-less, so this path is exempted from the session gate. `{splat}` stands in for the whole remainder of the path (it may contain `/`); the bare `/api/workbench/serve/{token}` form (root → index.html) is registered the same way with no remainder.","parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"},{"schema":{"type":"string","description":"The remainder path under `cwd`; may contain `/`."},"required":true,"description":"The remainder path under `cwd`; may contain `/`.","name":"splat","in":"path"}],"responses":{"200":{"description":"File contents, content-typed by extension"},"400":{"description":"Invalid path (null byte, symlink loop, not a directory)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Token expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token forged/malformed, wrong scope, or path escapes the boundary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/commands":{"get":{"tags":["Commands"],"summary":"List all slash commands","parameters":[{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"refresh","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cwd","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sessionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"runtime","in":"query"}],"responses":{"200":{"description":"Command registry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandRegistry"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks":{"get":{"tags":["Tasks"],"summary":"List all schedules","responses":{"200":{"description":"Array of schedules, each with its next run and a preview of the few after it","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}}}},"post":{"tags":["Tasks"],"summary":"Create a schedule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequest"}}}},"responses":{"201":{"description":"Created schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"CWD outside directory boundary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks/{id}":{"patch":{"tags":["Tasks"],"summary":"Update a schedule","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskRequest"}}}},"responses":{"200":{"description":"Updated schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Tasks"],"summary":"Delete a schedule","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks/{id}/trigger":{"post":{"tags":["Tasks"],"summary":"Manually trigger a schedule run","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"}},"required":["runId"]}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks/runs":{"get":{"tags":["Tasks"],"summary":"List runs","parameters":[{"schema":{"type":"string"},"required":false,"name":"scheduleId","in":"query"},{"schema":{"$ref":"#/components/schemas/TaskRunStatus"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Array of runs","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskRun"}}}}}}}},"/api/tasks/runs/{id}":{"get":{"tags":["Tasks"],"summary":"Get a specific run","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Run details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRun"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tasks/runs/{id}/cancel":{"post":{"tags":["Tasks"],"summary":"Stop a running job","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"A runner has the stop request, or the run had already finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelTaskRunResponse"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The stop request went out and nothing acknowledged it — the run may still be going","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/messages":{"post":{"tags":["Relay"],"summary":"Send a relay message","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelaySendMessageRequest"}}}},"responses":{"200":{"description":"Message sent","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string"},"deliveredTo":{"type":"number"}},"required":["messageId","deliveredTo"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Relay"],"summary":"List relay messages","parameters":[{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","enum":["new","cur","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Array of messages with cursor","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/RelayEnvelope"}},"cursor":{"type":"string"}},"required":["messages"]}}}}}}},"/api/relay/messages/{id}":{"get":{"tags":["Relay"],"summary":"Get a specific message","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Message details with per-endpoint delivery breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"endpointHash":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"sender":{"type":["string","null"]},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"endpointHash":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"sender":{"type":["string","null"]}},"required":["id","subject","endpointHash","status","createdAt","expiresAt"]}}},"required":["id","subject","endpointHash","status","createdAt","expiresAt","deliveries"]}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/endpoints":{"get":{"tags":["Relay"],"summary":"List registered endpoints","responses":{"200":{"description":"Array of endpoints","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"description":{"type":"string"}},"required":["subject"]}}}}}}},"post":{"tags":["Relay"],"summary":"Register an endpoint","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointRegistration"}}}},"responses":{"201":{"description":"Endpoint registered","content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"created":{"type":"boolean"}},"required":["subject","created"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/endpoints/{subject}":{"delete":{"tags":["Relay"],"summary":"Unregister an endpoint","parameters":[{"schema":{"type":"string"},"required":true,"name":"subject","in":"path"}],"responses":{"200":{"description":"Endpoint removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"404":{"description":"Endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/endpoints/{subject}/inbox":{"get":{"tags":["Relay"],"summary":"Read inbox for an endpoint","description":"Defaults to `pending` messages only, so budget-rejected `failed` messages never surface next to deliverables unless a caller explicitly opts in via `?status=`.","parameters":[{"schema":{"type":"string"},"required":true,"name":"subject","in":"path"},{"schema":{"$ref":"#/components/schemas/InboxStatusFilter"},"required":false,"description":"Filter messages by status. Defaults to \"pending\" (deliverable, unread messages) so budget-rejected failures never surface silently next to real deliverables. Pass \"failed\" to see budget-rejected/dead-lettered messages, \"delivered\" for already-read ones (metadata only — the payload is removed once a message completes), or \"all\" for every status.","name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Inbox messages with cursor","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"endpointHash":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"sender":{"type":["string","null"]},"payload":{"description":"Envelope payload read from Maildir; null once the message is acknowledged"}},"required":["id","subject","endpointHash","status","createdAt","expiresAt"]}},"nextCursor":{"type":"string"}},"required":["messages"]}}}},"404":{"description":"Endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/dead-letters":{"get":{"tags":["Relay"],"summary":"List dead-letter messages","parameters":[{"schema":{"type":"string","pattern":"^(adapter:)?[A-Za-z0-9_*>-]+(\\.[A-Za-z0-9_*>-]+)*$","description":"Only list dead letters filed for this endpoint hash."},"required":false,"description":"Only list dead letters filed for this endpoint hash.","name":"endpointHash","in":"query"}],"responses":{"200":{"description":"Dead-letter messages","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/RelayEnvelope"}},"cursor":{"type":"string"}},"required":["messages"]}}}}}}},"/api/relay/metrics":{"get":{"tags":["Relay"],"summary":"Relay system metrics","responses":{"200":{"description":"Metrics data","content":{"application/json":{"schema":{"type":"object","properties":{"totalMessages":{"type":"number"},"totalEndpoints":{"type":"number"},"totalDeadLetters":{"type":"number"}},"required":["totalMessages","totalEndpoints","totalDeadLetters"]}}}}}}},"/api/relay/stream":{"get":{"tags":["Relay"],"summary":"SSE event stream for relay activity","description":"Server-Sent Events stream for real-time relay activity. Supports server-side subject filtering via query param. Event types: relay_connected, relay_message, relay_delivery, relay_dead_letter, relay_metrics.","parameters":[{"schema":{"type":"string","description":"Subject pattern filter"},"required":false,"description":"Subject pattern filter","name":"subject","in":"query"}],"responses":{"200":{"description":"SSE event stream","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream"}}}}}}},"/api/mesh/discover":{"post":{"tags":["Mesh"],"summary":"Discover mesh agents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverRequest"}}}},"responses":{"200":{"description":"Discovered candidates","content":{"application/json":{"schema":{"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveryCandidate"}}},"required":["candidates"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/agents":{"post":{"tags":["Mesh"],"summary":"Register a mesh agent","description":"A directory that already holds a `.dork/agent.json` is ADOPTED, never overwritten: the file is left untouched and the agent it describes is what gets registered, so the returned id and name can differ from the ones sent, and `overrides` may be omitted entirely. A manifest that is there but cannot be read is refused with a 422 rather than replaced. `overrides.name` and `overrides.runtime` are required only for a directory that has no manifest to adopt. Registering also clears any denial recorded against the directory.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentRequest"}}}},"responses":{"201":{"description":"Registered agent (adopted, when the directory already had one)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Registration refused — an existing manifest there could not be read or adopted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Mesh"],"summary":"List mesh agents","parameters":[{"schema":{"$ref":"#/components/schemas/AgentRuntime"},"required":false,"name":"runtime","in":"query"},{"schema":{"type":"string"},"required":false,"name":"capability","in":"query"},{"schema":{"type":"string"},"required":false,"name":"callerNamespace","in":"query"}],"responses":{"200":{"description":"Array of agents","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentManifest"}}},"required":["agents"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/agents/{id}":{"get":{"tags":["Mesh"],"summary":"Get mesh agent","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Mesh"],"summary":"Update mesh agent","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentRequest"}}}},"responses":{"200":{"description":"Updated agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Mesh"],"summary":"Unregister mesh agent","description":"Removes the agent and deletes its `.dork/agent.json`, so the next scan does not adopt it back — unless git is tracking that file, which makes it part of a repository rather than DorkOS's bookkeeping. Then the file is left alone and the directory is denied instead, and `blockedFromDiscovery` says so. Registering the directory again clears that denial.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"blockedFromDiscovery":{"type":"boolean"}},"required":["success","blockedFromDiscovery"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/topology":{"get":{"tags":["Mesh"],"summary":"Get mesh topology","description":"Every agent on this machine, grouped by namespace, with the access rules that decide who can message whom. The view is scoped to what the caller can reach: namespaces the caller has no access to are omitted entirely. `openMesh` reports the mesh-wide \"let all my agents talk to each other\" switch.","parameters":[{"schema":{"type":"string","description":"The calling agent's namespace, which scopes the view to the namespaces it can reach. Defaults to `*`, the unscoped admin view.","example":"*"},"required":false,"description":"The calling agent's namespace, which scopes the view to the namespaces it can reach. Defaults to `*`, the unscoped admin view.","name":"namespace","in":"query"}],"responses":{"200":{"description":"Topology view scoped to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopologyView"}}}}}}},"/api/mesh/topology/access":{"put":{"tags":["Mesh"],"summary":"Update a mesh access rule","description":"Grant or revoke one directional access rule between two namespaces — `allow` lets agents in the source namespace message agents in the target one, `deny` takes that grant away. Rules are one-way: allowing `a -> b` does not let `b` answer back.\n\n`*` on BOTH sides is the mesh-wide \"let all my agents talk to each other\" switch: `allow` turns it on, `deny` turns it off. `*` on one side only is rejected with a 400 — it would open far more traffic than the caller asked for.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccessRuleRequest"}}}},"responses":{"200":{"description":"The rule as applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossNamespaceRule"}}}},"400":{"description":"Validation error, including `*` on one side only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/deny":{"post":{"tags":["Mesh"],"summary":"Deny a mesh candidate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DenyRequest"}}}},"responses":{"200":{"description":"Candidate denied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/denied":{"get":{"tags":["Mesh"],"summary":"List denied mesh candidates","responses":{"200":{"description":"Denied candidates","content":{"application/json":{"schema":{"type":"object","properties":{"denied":{"type":"array","items":{"$ref":"#/components/schemas/DenialRecord"}}},"required":["denied"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mesh/denied/{encodedPath}":{"delete":{"tags":["Mesh"],"summary":"Clear mesh denial","parameters":[{"schema":{"type":"string"},"required":true,"name":"encodedPath","in":"path"}],"responses":{"200":{"description":"Denial cleared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/sources":{"get":{"tags":["Marketplace"],"summary":"List configured marketplace sources","responses":{"200":{"description":"Configured marketplace sources","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"source":{"type":"string"},"enabled":{"type":"boolean"},"addedAt":{"type":"string"}},"required":["name","source","enabled","addedAt"]}}},"required":["sources"]}}}}}},"post":{"tags":["Marketplace"],"summary":"Add a marketplace source (operator only)","description":"Only the person running DorkOS may add a package source. Any caller that could not decide an approval is refused with 403, which includes one presenting an agent identity, one presenting an approval token, and (with local login on) one with no signed-in identity. There is no approval that unlocks it.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"source":{"type":"string","minLength":1},"enabled":{"type":"boolean"}},"required":["name","source"]}}}},"responses":{"201":{"description":"Source added","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"source":{"type":"string"},"enabled":{"type":"boolean"},"addedAt":{"type":"string"}},"required":["name","source","enabled","addedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Caller is not the operator","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["operator_only_marketplace_source"]},"message":{"type":"string"}},"required":["error","code","message"]}}}},"409":{"description":"Duplicate source name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/sources/{name}":{"delete":{"tags":["Marketplace"],"summary":"Remove a marketplace source (operator only)","description":"Only the person running DorkOS may remove a package source. Any caller that could not decide an approval is refused with 403, which includes one presenting an agent identity, one presenting an approval token, and (with local login on) one with no signed-in identity. There is no approval that unlocks it.","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"204":{"description":"Source removed"},"403":{"description":"Caller is not the operator","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["operator_only_marketplace_source"]},"message":{"type":"string"}},"required":["error","code","message"]}}}}}}},"/api/marketplace/sources/{name}/refresh":{"post":{"tags":["Marketplace"],"summary":"Force refetch of a source marketplace.json","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Refreshed marketplace document","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"type":"object","properties":{"name":{"type":"string"},"plugins":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"source":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"}},"required":["name","source"],"additionalProperties":{}}}},"required":["name","plugins"],"additionalProperties":{}},"fetchedAt":{"type":"string"}},"required":["marketplace","fetchedAt"]}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream fetch failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/installed":{"get":{"tags":["Marketplace"],"summary":"List installed marketplace packages","description":"Without projectPath: one entry per installation across all scopes (global roots plus every registered agent's local installs), each tagged with scope and agent identity. With projectPath: the merged view for that single project — one entry per package name.","parameters":[{"schema":{"type":"string"},"required":false,"name":"projectPath","in":"query"}],"responses":{"200":{"description":"Installed packages","content":{"application/json":{"schema":{"type":"object","properties":{"packages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"installPath":{"type":"string"},"installedFrom":{"type":"string"},"installedAt":{"type":"string"},"scope":{"type":"string","enum":["global","agent-local","override"]},"agentPath":{"type":"string"},"agentId":{"type":"string"},"agentName":{"type":"string"}},"required":["name","version","type","installPath"]}}},"required":["packages"]}}}}}}},"/api/marketplace/installed/{name}":{"get":{"tags":["Marketplace"],"summary":"List every installation of a package","description":"Every installation of the named package across all scopes (global + each agent), each enriched with capability counts (commands, skills, hooks).","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Installations of the package","content":{"application/json":{"schema":{"type":"object","properties":{"installations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"installPath":{"type":"string"},"installedFrom":{"type":"string"},"installedAt":{"type":"string"},"scope":{"type":"string","enum":["global","agent-local","override"]},"agentPath":{"type":"string"},"agentId":{"type":"string"},"agentName":{"type":"string"},"provides":{"type":"object","properties":{"commands":{"type":"integer","minimum":0},"skills":{"type":"integer","minimum":0},"hooks":{"type":"boolean"}},"required":["commands","skills","hooks"]},"dependencyWarnings":{"type":"array","items":{"type":"string"}}},"required":["name","version","type","installPath"]}}},"required":["installations"]}}}},"404":{"description":"Package not installed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/cache":{"get":{"tags":["Marketplace"],"summary":"Marketplace cache status","responses":{"200":{"description":"Cache counts and total size","content":{"application/json":{"schema":{"type":"object","properties":{"marketplaces":{"type":"integer","minimum":0},"packages":{"type":"integer","minimum":0},"totalSizeBytes":{"type":"integer","minimum":0}},"required":["marketplaces","packages","totalSizeBytes"]}}}}}},"delete":{"tags":["Marketplace"],"summary":"Clear the marketplace cache","responses":{"204":{"description":"Cache cleared"}}}},"/api/marketplace/cache/prune":{"post":{"tags":["Marketplace"],"summary":"Garbage-collect cached packages, keeping the N most recent per name","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"keepLastN":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Prune result","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"array","items":{"type":"object","properties":{"packageName":{"type":"string"},"commitSha":{"type":"string"},"path":{"type":"string"},"cachedAt":{"type":"string"}},"required":["packageName","commitSha","path","cachedAt"]}},"freedBytes":{"type":"integer","minimum":0}},"required":["removed","freedBytes"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/packages":{"get":{"tags":["Marketplace"],"summary":"List installable packages (aggregated from every enabled source)","responses":{"200":{"description":"Aggregated package list","content":{"application/json":{"schema":{"type":"object","properties":{"packages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"source":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"marketplace":{"type":"string"}},"required":["name","source","marketplace"],"additionalProperties":{}}}},"required":["packages"]}}}},"500":{"description":"Aggregation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/packages/{name}":{"get":{"tags":["Marketplace"],"summary":"Get package details (fetches, validates, builds a preview)","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string"},"required":false,"name":"marketplace","in":"query"}],"responses":{"200":{"description":"Package manifest, staged path, permission preview, and optional README","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"type":"object","properties":{"schemaVersion":{"type":"number"},"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"description":{"type":"string"}},"required":["schemaVersion","name","version","type"],"additionalProperties":{}},"packagePath":{"type":"string"},"preview":{"type":"object","properties":{"fileChanges":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"action":{"type":"string","enum":["create","modify","delete"]}},"required":["path","action"]}},"extensions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slots":{"type":"array","items":{"type":"string"}}},"required":["id","slots"]}},"hooks":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"matcher":{"type":"string"},"command":{"type":"string"}},"required":["event","command"]}},"unreadableHooks":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"event":{"type":"string"}},"required":["path"]}},"schedules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cron":{"type":["string","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"startsEnabled":{"type":"boolean"}},"required":["name","cron","permissionMode","startsEnabled"]}},"secrets":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["key","required"]}},"npmDependencies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"range":{"type":"string"},"optional":{"type":"boolean"}},"required":["name","range"]}},"externalHosts":{"type":"array","items":{"type":"string"}},"requires":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"satisfied":{"type":"boolean"}},"required":["type","name","satisfied"]}},"conflicts":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["error","warning"]},"type":{"type":"string","enum":["package-name","slot","skill-name","task-name","cron-collision","adapter-id"]},"description":{"type":"string"},"conflictingPackage":{"type":"string"}},"required":["level","type","description"]}}},"required":["fileChanges","extensions","hooks","unreadableHooks","schedules","secrets","npmDependencies","externalHosts","requires","conflicts"]},"readme":{"type":"string"}},"required":["manifest","packagePath","preview"]}}}},"400":{"description":"Validation error or invalid package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Marketplace or package not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/packages/{name}/preview":{"post":{"tags":["Marketplace"],"summary":"Build a permission preview without installing","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"type":"string"},"source":{"type":"string"},"force":{"type":"boolean"},"yes":{"type":"boolean"},"projectPath":{"type":"string"}}}}}},"responses":{"200":{"description":"Permission preview, manifest, and staged path","content":{"application/json":{"schema":{"type":"object","properties":{"preview":{"type":"object","properties":{"fileChanges":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"action":{"type":"string","enum":["create","modify","delete"]}},"required":["path","action"]}},"extensions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slots":{"type":"array","items":{"type":"string"}}},"required":["id","slots"]}},"hooks":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"matcher":{"type":"string"},"command":{"type":"string"}},"required":["event","command"]}},"unreadableHooks":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"event":{"type":"string"}},"required":["path"]}},"schedules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cron":{"type":["string","null"]},"permissionMode":{"$ref":"#/components/schemas/PermissionMode"},"startsEnabled":{"type":"boolean"}},"required":["name","cron","permissionMode","startsEnabled"]}},"secrets":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["key","required"]}},"npmDependencies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"range":{"type":"string"},"optional":{"type":"boolean"}},"required":["name","range"]}},"externalHosts":{"type":"array","items":{"type":"string"}},"requires":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"satisfied":{"type":"boolean"}},"required":["type","name","satisfied"]}},"conflicts":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["error","warning"]},"type":{"type":"string","enum":["package-name","slot","skill-name","task-name","cron-collision","adapter-id"]},"description":{"type":"string"},"conflictingPackage":{"type":"string"}},"required":["level","type","description"]}}},"required":["fileChanges","extensions","hooks","unreadableHooks","schedules","secrets","npmDependencies","externalHosts","requires","conflicts"]},"manifest":{"type":"object","properties":{"schemaVersion":{"type":"number"},"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"description":{"type":"string"}},"required":["schemaVersion","name","version","type"],"additionalProperties":{}},"packagePath":{"type":"string"}},"required":["preview","manifest","packagePath"]}}}},"400":{"description":"Validation error or invalid package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Marketplace or package not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/packages/{name}/install":{"post":{"tags":["Marketplace"],"summary":"Install a marketplace package","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"type":"string"},"source":{"type":"string"},"force":{"type":"boolean"},"yes":{"type":"boolean"},"projectPath":{"type":"string"}}}}}},"responses":{"200":{"description":"Install result from the type-specific flow","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"packageName":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"installPath":{"type":"string"},"manifest":{"type":"object","properties":{"schemaVersion":{"type":"number"},"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"description":{"type":"string"}},"required":["schemaVersion","name","version","type"],"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"string"}},"dependencyWarnings":{"type":"array","items":{"type":"string"}}},"required":["ok","packageName","version","type","installPath","manifest","warnings"]}}}},"400":{"description":"Validation error or invalid package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Marketplace or package not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Install blocked by conflicts","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"conflicts":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["error","warning"]},"type":{"type":"string","enum":["package-name","slot","skill-name","task-name","cron-collision","adapter-id"]},"description":{"type":"string"},"conflictingPackage":{"type":"string"}},"required":["level","type","description"]}}},"required":["error","conflicts"]}}}}}}},"/api/marketplace/packages/{name}/uninstall":{"post":{"tags":["Marketplace"],"summary":"Uninstall a marketplace package","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"purge":{"type":"boolean"},"projectPath":{"type":"string"}}}}}},"responses":{"200":{"description":"Uninstall result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"packageName":{"type":"string"},"removedFiles":{"type":"integer","minimum":0},"preservedData":{"type":"array","items":{"type":"string"}}},"required":["ok","packageName","removedFiles","preservedData"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Package not installed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/marketplace/packages/{name}/update":{"post":{"tags":["Marketplace"],"summary":"Advisory update check (pass apply:true to actually update)","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apply":{"type":"boolean"},"projectPath":{"type":"string"}}}}}},"responses":{"200":{"description":"Update advisory result (and any applied reinstalls)","content":{"application/json":{"schema":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"packageName":{"type":"string"},"installedVersion":{"type":"string"},"latestVersion":{"type":"string"},"hasUpdate":{"type":"boolean"},"marketplace":{"type":"string"}},"required":["packageName","installedVersion","latestVersion","hasUpdate","marketplace"]}},"applied":{"type":"array","items":{"type":"object","properties":{"ok":{"type":"boolean"},"packageName":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"installPath":{"type":"string"},"manifest":{"type":"object","properties":{"schemaVersion":{"type":"number"},"name":{"type":"string"},"version":{"type":"string"},"type":{"type":"string","enum":["agent","plugin","skill-pack","adapter","shape"]},"description":{"type":"string"}},"required":["schemaVersion","name","version","type"],"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"string"}},"dependencyWarnings":{"type":"array","items":{"type":"string"}}},"required":["ok","packageName","version","type","installPath","manifest","warnings"]}}},"required":["checks","applied"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Package not installed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/cloud/link/start":{"post":{"tags":["Cloud"],"summary":"Begin the device flow to link this instance to a DorkOS account","description":"Requests a device code from the DorkOS cloud and starts a background poll. Returns the user code + verification URI for the human to approve; poll GET /api/cloud/link/status for the outcome. Independent of local login (config.auth.enabled).","responses":{"200":{"description":"Device codes to display","content":{"application/json":{"schema":{"type":"object","properties":{"userCode":{"type":"string","description":"The 8-character code the human enters at the cloud."},"verificationUri":{"type":"string","description":"Where the human goes to approve the link."},"expiresAt":{"type":"string","description":"ISO timestamp after which the code is dead."}},"required":["userCode","verificationUri","expiresAt"]}}}},"502":{"description":"Could not reach the DorkOS cloud","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/cloud/link/status":{"get":{"tags":["Cloud"],"summary":"Current device-link flow state","responses":{"200":{"description":"Link-flow state machine","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["idle","pending","linked","expired","denied","unlinked"]},"accountLabel":{"type":"string"},"lastHeartbeatAt":{"type":"string"}},"required":["state"]}}}}}}},"/api/cloud/unlink":{"post":{"tags":["Cloud"],"summary":"Unlink this instance (best-effort cloud revoke, then clear local state)","responses":{"200":{"description":"Unlinked","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"500":{"description":"Unlink failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/cloud/status":{"get":{"tags":["Cloud"],"summary":"Settled linked/unlinked summary for Settings","responses":{"200":{"description":"Linked state, account label, and last heartbeat","content":{"application/json":{"schema":{"type":"object","properties":{"linked":{"type":"boolean"},"accountLabel":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]}},"required":["linked","accountLabel","lastHeartbeatAt"]}}}}}}},"/api/shapes":{"get":{"tags":["Shapes"],"summary":"List installed Shapes","description":"Returns every installed Shape with its display name, active flag (`ui.shapes.active`), and fork lineage.","responses":{"200":{"description":"Installed Shapes","content":{"application/json":{"schema":{"type":"object","properties":{"shapes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"lineage":{"type":"object","properties":{"forkedFrom":{"type":"string"},"forkedFromVersion":{"type":"string"},"forkedAt":{"type":"string"}},"required":["forkedFrom","forkedAt"]}},"required":["name","active"]}}},"required":["shapes"]}}}}}}},"/api/shapes/{name}/apply":{"post":{"tags":["Shapes"],"summary":"Apply an installed Shape","description":"Enables the Shape’s extensions, resolves connections, stands up schedules, offers agents (never forces one), and records the active Shape. Only \"Shape not installed\" is fatal (404); every other missing piece degrades to a `warnings[]` entry. `applied.layout` carries the chrome the client restores without a second fetch (spec §5/§9).","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Apply result (chrome + activated extensions + created schedules, warnings, offers)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyShapeResult"}}}},"404":{"description":"Shape is not installed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/shapes/{name}/fork":{"post":{"tags":["Shapes"],"summary":"Fork an installed Shape","description":"Clones an installed Shape into a new, independently-editable one and stamps `lineage`. `captureCurrent` snapshots the live arrangement when forking the active Shape: the currently-enabled extensions (read server-side) plus the caller’s `liveLayout`. `liveLayout` is a PARTIAL chrome snapshot merged field-wise over the source Shape’s `layout` — every field the caller omits keeps the source’s value, so a client never overwrites chrome it cannot observe.","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkShapeRequest"}}}},"responses":{"201":{"description":"The forked Shape descriptor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkShapeResult"}}}},"404":{"description":"Source Shape is not installed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Fork name is invalid or already taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/providers":{"get":{"tags":["Connectors"],"summary":"List connector provider setup statuses","description":"Reference-free setup state per credential-gated provider: configured/registered booleans, the custody stance with its plain-language disclosure, and — when a configured provider refused to register — the honest error text. Never carries a secret or a credential reference.","responses":{"200":{"description":"Provider setup statuses","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"configured":{"type":"boolean"},"registered":{"type":"boolean"},"custody":{"type":"string","enum":["managed","self-host","external"]},"disclosure":{"type":"string"},"error":{"type":"string"},"keyKind":{"type":"string","enum":["project","user","unknown"]}},"required":["type","configured","registered","custody","disclosure"]}}},"required":["providers"]}}}}}}},"/api/connectors/providers/{provider}/credential":{"put":{"tags":["Connectors"],"summary":"Store a provider vendor key and register the provider live","description":"Stores the key in the encrypted credential store and reloads the provider — no restart. The secret is never echoed; the response is the fresh provider status.","parameters":[{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string","minLength":1}},"required":["secret"]}}}},"responses":{"200":{"description":"The provider status after the reload","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"configured":{"type":"boolean"},"registered":{"type":"boolean"},"custody":{"type":"string","enum":["managed","self-host","external"]},"disclosure":{"type":"string"},"error":{"type":"string"},"keyKind":{"type":"string","enum":["project","user","unknown"]}},"required":["type","configured","registered","custody","disclosure"]}}}},"400":{"description":"Unknown provider or empty secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Connectors"],"summary":"Remove a provider vendor key (idempotent) and unregister the provider","description":"Deletes the stored key and reloads the provider, which unregisters it. Idempotent — a missing key still answers 200 with the (unconfigured) status.","parameters":[{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"The provider status after the reload","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"configured":{"type":"boolean"},"registered":{"type":"boolean"},"custody":{"type":"string","enum":["managed","self-host","external"]},"disclosure":{"type":"string"},"error":{"type":"string"},"keyKind":{"type":"string","enum":["project","user","unknown"]}},"required":["type","configured","registered","custody","disclosure"]}}}},"400":{"description":"Unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/catalog":{"get":{"tags":["Connectors"],"summary":"List the provider-neutral connector catalog","description":"Returns one bounded account-free page. Native message adapters remain distinct from account routes.","parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":500},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Account-free connector catalog page","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"serviceSlug":{"type":"string","minLength":1,"maxLength":200},"displayName":{"type":"string","minLength":1,"maxLength":200},"iconKey":{"type":"string","minLength":1,"maxLength":200},"intents":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["messages"]},"displayName":{"type":"string","minLength":1,"maxLength":200},"relayAdapterType":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","displayName","relayAdapterType"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["account"]},"displayName":{"type":"string","minLength":1,"maxLength":200},"routes":{"type":"array","items":{"type":"object","properties":{"providerInstanceId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1,"maxLength":200},"mode":{"type":"string","enum":["managed","byo"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"capabilities":{"type":"object","properties":{"catalog":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"authentication":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"accounts":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"operations":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"execution":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"triggers":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]}},"required":["catalog","authentication","accounts","operations","execution","triggers"]},"disclosure":{"type":"string","minLength":1,"maxLength":1000},"authKind":{"type":"string","enum":["oauth2","api-key","none"]},"authenticationSetup":{"type":"object","properties":{"kind":{"type":"string","enum":["oauth","fields","none","unsupported"]},"source":{"type":"string","enum":["configured","managed","account-fields","unsupported"]},"scheme":{"type":"string","minLength":1,"maxLength":100},"requiresAccountFields":{"type":"boolean"}},"required":["kind","source","requiresAccountFields"],"additionalProperties":false}},"required":["providerInstanceId","displayName","mode","custody","payer","capabilities","disclosure","authKind"],"additionalProperties":false},"minItems":1,"maxItems":20}},"required":["kind","displayName","routes"],"additionalProperties":false}]},"minItems":1,"maxItems":20}},"required":["serviceSlug","displayName","iconKey","intents"],"additionalProperties":false},"maxItems":100},"nextCursor":{"type":"string","minLength":1,"maxLength":500},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false},"maxItems":50}},"required":["services","warnings"],"additionalProperties":false}}}},"400":{"description":"Invalid catalog query or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections":{"get":{"tags":["Connectors"],"summary":"List the operator’s stable connections","responses":{"200":{"description":"Owner-scoped stable connection inventory","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"identityHint":{"type":["string","null"],"minLength":1,"maxLength":500},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed","unknown"]},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"mode":{"type":"string","enum":["managed","byo"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"agentCount":{"type":"integer","minimum":0},"subscriptionCount":{"type":"integer","minimum":0},"usage":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]},"logicalOperationCount":{"type":"integer","minimum":0},"attemptCount":{"type":"integer","minimum":0}},"required":["status","logicalOperationCount","attemptCount"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false},"maxItems":50}},"required":["connectionId","providerInstanceId","toolkit","label","identityHint","lifecycle","authenticationStatus","reconciliationStatus","authoritySync","mode","custody","payer","agentCount","subscriptionCount","usage","warnings"],"additionalProperties":false},"maxItems":10000}},"required":["connections"],"additionalProperties":false}}}},"403":{"description":"Verified operator authority is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Connectors"],"summary":"Start a restart-safe connector authentication flow","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["providerInstanceId","toolkit","idempotencyKey"],"additionalProperties":false}}}},"responses":{"201":{"description":"Durable owner-only authentication flow state","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["starting"]}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending"]},"authorizeUrl":{"type":"string","format":"uri"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["connected"]},"connectionId":{"type":"string","minLength":1},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","connectionId","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["expired"]},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["start_unknown"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false}]}}}},"403":{"description":"Verified operator authority is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The idempotency key belongs to a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Authentication is unavailable for the selected provider route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/authentication-flows/{flowId}":{"get":{"tags":["Connectors"],"summary":"Poll one durable connector authentication flow","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"flowId","in":"path"}],"responses":{"200":{"description":"Current owner-only authentication state","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["starting"]}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending"]},"authorizeUrl":{"type":"string","format":"uri"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["connected"]},"connectionId":{"type":"string","minLength":1},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","connectionId","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["expired"]},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["start_unknown"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false}]}}}},"404":{"description":"Flow absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}":{"get":{"tags":["Connectors"],"summary":"Read one stable connection and its exact grants","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Owner-visible connection detail","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"identityHint":{"type":["string","null"],"minLength":1,"maxLength":500},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed","unknown"]},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"mode":{"type":"string","enum":["managed","byo"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"agentCount":{"type":"integer","minimum":0},"subscriptionCount":{"type":"integer","minimum":0},"usage":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]},"logicalOperationCount":{"type":"integer","minimum":0},"attemptCount":{"type":"integer","minimum":0}},"required":["status","logicalOperationCount","attemptCount"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false},"maxItems":50}},"required":["connectionId","providerInstanceId","toolkit","label","identityHint","lifecycle","authenticationStatus","reconciliationStatus","authoritySync","mode","custody","payer","agentCount","subscriptionCount","usage","warnings"],"additionalProperties":false},"provider":{"type":"object","properties":{"providerInstanceId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1,"maxLength":200},"mode":{"type":"string","enum":["managed","byo"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"capabilities":{"type":"object","properties":{"catalog":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"authentication":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"accounts":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"operations":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"execution":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]},"triggers":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]}},"required":["catalog","authentication","accounts","operations","execution","triggers"]},"disclosure":{"type":"string","minLength":1,"maxLength":1000}},"required":["providerInstanceId","displayName","mode","custody","payer","capabilities","disclosure"],"additionalProperties":false},"agents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"maxLength":200},"displayName":{"type":"string","minLength":1,"maxLength":200},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100000},"classifications":{"type":"array","items":{"type":"string","enum":["read","write","destructive"]},"maxItems":3},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]}},"required":["agentId","displayName","operationRevisionIds","classifications","reconciliationStatus","authoritySync"],"additionalProperties":false},"maxItems":500},"sessions":{"type":"object","properties":{"affectedCount":{"type":"integer","minimum":0}},"required":["affectedCount"],"additionalProperties":false},"subscriptions":{"type":"object","properties":{"totalCount":{"type":"integer","minimum":0},"activeCount":{"type":"integer","minimum":0},"capability":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["available"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"]}]}},"required":["totalCount","activeCount","capability"],"additionalProperties":false}},"required":["connection","provider","agents","sessions","subscriptions"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Connectors"],"summary":"Rename one stable connection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200}},"required":["label"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated lifecycle projection","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed"]},"warning":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false}},"required":["connectionId","lifecycle","authenticationStatus","authoritySync","externalCleanup"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Connectors"],"summary":"Disconnect one stable connection","description":"Closes local authority before provider or hosted cleanup is awaited.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Local lifecycle and external cleanup state","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed"]},"warning":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false}},"required":["connectionId","lifecycle","authenticationStatus","authoritySync","externalCleanup"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}/disconnect-impact":{"get":{"tags":["Connectors"],"summary":"Preview authority affected by disconnecting a connection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Current grant, session, and subscription impact","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"affectedAgentCount":{"type":"integer","minimum":0},"affectedSessionCount":{"type":"integer","minimum":0},"affectedSubscriptionCount":{"type":"integer","minimum":0},"pendingDeliveryCount":{"type":"integer","minimum":0}},"required":["connectionId","affectedAgentCount","affectedSessionCount","affectedSubscriptionCount","pendingDeliveryCount"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}/remove":{"post":{"tags":["Connectors"],"summary":"Remove a disconnected account from Accounts while retaining its history","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"204":{"description":"Account removed from the owner inventory"},"404":{"description":"Account absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Account must finish disconnecting before removal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}/reconnect":{"post":{"tags":["Connectors"],"summary":"Start an idempotent reconnect flow","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["idempotencyKey"],"additionalProperties":false}}}},"responses":{"201":{"description":"Durable owner-only authentication flow state","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["starting"]}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending"]},"authorizeUrl":{"type":"string","format":"uri"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["connected"]},"connectionId":{"type":"string","minLength":1},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","connectionId","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["expired"]},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","completedAt"],"additionalProperties":false},{"type":"object","properties":{"flowId":{"type":"string","minLength":1,"maxLength":200},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["start_unknown"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"completedAt":{"type":"string","format":"date-time"}},"required":["flowId","providerInstanceId","toolkit","createdAt","expiresAt","state","reason","completedAt"],"additionalProperties":false}]}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The idempotency key belongs to a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}/pause":{"post":{"tags":["Connectors"],"summary":"Pause one stable connection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Local lifecycle and managed authority synchronization state","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed"]},"warning":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false}},"required":["connectionId","lifecycle","authenticationStatus","authoritySync","externalCleanup"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/connections/{connectionId}/resume":{"post":{"tags":["Connectors"],"summary":"Resume one stable connection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"}],"responses":{"200":{"description":"Local lifecycle and managed authority synchronization state","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"externalCleanup":{"type":"string","enum":["not_required","pending","complete","failed"]},"warning":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"],"additionalProperties":false}},"required":["connectionId","lifecycle","authenticationStatus","authoritySync","externalCleanup"],"additionalProperties":false}}}},"404":{"description":"Connection absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/agents/{agentId}/connections":{"get":{"tags":["Connectors"],"summary":"Read exact connection grants for one owned agent","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path"}],"responses":{"200":{"description":"Canonical agent connection grants","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"maxLength":200},"connections":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"lifecycle":{"type":"string","enum":["connected","paused","disconnected"]},"authenticationStatus":{"type":"string","enum":["active","expired","revoked","pending"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100000},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]}},"required":["connectionId","toolkit","label","lifecycle","authenticationStatus","reconciliationStatus","operationRevisionIds","authoritySync"],"additionalProperties":false},"maxItems":500}},"required":["agentId","connections"],"additionalProperties":false}}}},"404":{"description":"Agent absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/sessions/{sessionId}/connections":{"get":{"tags":["Connectors"],"summary":"Read effective connector access for one session","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"Canonical session connector access","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"maxLength":200},"agentId":{"type":"string","minLength":1,"maxLength":200},"connections":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","minLength":1,"maxLength":200},"access":{"type":"string","enum":["inherited","session_only","disabled"]},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100000},"dominatingReason":{"type":"string","enum":["none","connection_paused","connection_revoked","authentication_required","grant_revoked","session_detached","reconciliation_required","authority_sync_required"]}},"required":["connectionId","toolkit","label","access","operationRevisionIds","dominatingReason"],"additionalProperties":false},"maxItems":500}},"required":["sessionId","agentId","connections"],"additionalProperties":false}}}},"404":{"description":"Session absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/reviews":{"post":{"tags":["Connectors"],"summary":"Create an owner-reviewed connector management request","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["action","idempotencyKey"],"additionalProperties":false}}}},"responses":{"201":{"description":"Owner review or requester-safe review status","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["denied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["applied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["connect_authentication_required"]},"reviewRequestId":{"type":"string","minLength":1},"authentication":{"type":"object","properties":{"authorizeUrl":{"type":"string","format":"uri"},"flowId":{"type":"string","minLength":1}},"required":["flowId"],"additionalProperties":false}},"required":["kind","reviewRequestId","authentication"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["outcome_unknown"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["denied"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["applied"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["authentication_required"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["outcome_unknown"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false}]}}}},"401":{"description":"A verified program credential is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Agent identity or an unverified operator is refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Connectors"],"summary":"List owner-visible connector reviews","parameters":[{"schema":{"type":"string","enum":["pending","resolved"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"Owner-visible reviews","content":{"application/json":{"schema":{"type":"object","properties":{"reviews":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["denied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["applied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["connect_authentication_required"]},"reviewRequestId":{"type":"string","minLength":1},"authentication":{"type":"object","properties":{"authorizeUrl":{"type":"string","format":"uri"},"flowId":{"type":"string","minLength":1}},"required":["flowId"],"additionalProperties":false}},"required":["kind","reviewRequestId","authentication"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["outcome_unknown"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false}]}}},"required":["reviews"],"additionalProperties":false}}}}}}},"/api/connectors/program/reviews/{reviewRequestId}":{"get":{"tags":["Connectors"],"summary":"Read requester-safe status for one program review","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"reviewRequestId","in":"path"}],"responses":{"200":{"description":"Requester-safe lifecycle and outcome","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["denied"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["applied"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["authentication_required"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"reviewUrl":{"type":"string"},"targetStatus":{"type":"string","enum":["available","unavailable"]},"expiresAt":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["outcome_unknown"]}},"required":["reviewRequestId","reviewUrl","targetStatus","expiresAt","state","resolvedAt","outcome"],"additionalProperties":false}]}}}},"404":{"description":"Review absent or belongs to another requester","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/reviews/{reviewRequestId}":{"get":{"tags":["Connectors"],"summary":"Read one owner-visible connector review","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"reviewRequestId","in":"path"}],"responses":{"200":{"description":"Owner-visible review context and lifecycle","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["denied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["applied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["connect_authentication_required"]},"reviewRequestId":{"type":"string","minLength":1},"authentication":{"type":"object","properties":{"authorizeUrl":{"type":"string","format":"uri"},"flowId":{"type":"string","minLength":1}},"required":["flowId"],"additionalProperties":false}},"required":["kind","reviewRequestId","authentication"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["outcome_unknown"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false}]}}}},"404":{"description":"Review absent or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/reviews/{reviewRequestId}/decision":{"post":{"tags":["Connectors"],"summary":"Resolve one pending connector review","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"reviewRequestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","denied"]}},"required":["decision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Durably resolved review","content":{"application/json":{"schema":{"type":"object","properties":{"review":{"anyOf":[{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["pending"]}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["resolving"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["expired"]},"resolvedAt":{"type":"string","format":"date-time"}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["denied"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["denied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["applied"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["connect_authentication_required"]},"reviewRequestId":{"type":"string","minLength":1},"authentication":{"type":"object","properties":{"authorizeUrl":{"type":"string","format":"uri"},"flowId":{"type":"string","minLength":1}},"required":["flowId"],"additionalProperties":false}},"required":["kind","reviewRequestId","authentication"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false},{"type":"object","properties":{"reviewRequestId":{"type":"string","minLength":1},"requesterKind":{"type":"string","enum":["program","operator"]},"context":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"providerDisplayName":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","providerInstanceId","providerDisplayName","toolkit"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["edit","pause","resume"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false}},"required":["kind","connection"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["disconnect"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"affectedAgentCount":{"type":"integer","minimum":0},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","affectedAgentCount","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["set_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"requestedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false},"minItems":1}},"required":["kind","connection","agent","requestedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["remove_agent_access"]},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"providerDisplayName":{"type":"string","minLength":1},"providerStatus":{"type":"string","enum":["available","unavailable","migration_failed"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","label","toolkit","status","custody","providerDisplayName","providerStatus","reconciliationStatus"],"additionalProperties":false},"agent":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false},"affectedOperations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]}},"required":["operationRevisionId","operationSlug","toolkitVersion","capabilityClassification"],"additionalProperties":false}}},"required":["kind","connection","agent","affectedOperations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["created_before_context_snapshot"]}},"required":["kind","reason"],"additionalProperties":false}]},"targetStatus":{"type":"string","enum":["available","unavailable"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"action":{"oneOf":[{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["connect"]},"providerInstanceId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["version","kind","providerInstanceId","toolkit"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["edit"]},"label":{"type":"string","minLength":1}},"required":["version","connectionId","kind","label"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["pause"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["resume"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["disconnect"]}},"required":["version","connectionId","kind"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["set_agent_access"]},"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["version","connectionId","kind","agentId","operationRevisionIds"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number","enum":[1]},"connectionId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["remove_agent_access"]},"agentId":{"type":"string","minLength":1}},"required":["version","connectionId","kind","agentId"],"additionalProperties":false}]},"state":{"type":"string","enum":["approved"]},"resolvedAt":{"type":"string","format":"date-time"},"resolution":{"type":"object","properties":{"kind":{"type":"string","enum":["outcome_unknown"]}},"required":["kind"],"additionalProperties":false}},"required":["reviewRequestId","requesterKind","context","targetStatus","createdAt","expiresAt","action","state","resolvedAt","resolution"],"additionalProperties":false}]}},"required":["review"],"additionalProperties":false}}}},"409":{"description":"Review is no longer pending or the target changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/reconciliation/previews":{"post":{"tags":["Connectors"],"summary":"Preview a complete immutable grant revision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1}},"required":["connectionId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Complete immutable grant preview","content":{"application/json":{"schema":{"type":"object","properties":{"previewId":{"type":"string","minLength":1},"connection":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","toolkit","label","status","custody","reconciliationStatus"],"additionalProperties":false},"candidates":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]},"retryPolicy":{"type":"string","enum":["never","provider_idempotency_key"]},"inputSchema":{"type":"object","additionalProperties":{}},"supported":{"type":"boolean"}},"required":["operationRevisionId","toolkit","operationSlug","toolkitVersion","capabilityClassification","retryPolicy","inputSchema","supported"],"additionalProperties":false}},"agents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1}},"required":["agentId","displayName"],"additionalProperties":false}},"currentGrants":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1}}},"required":["agentId","operationRevisionIds"],"additionalProperties":false}},"catalogComplete":{"type":"boolean","enum":[true]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}},"required":["previewId","connection","candidates","agents","currentGrants","catalogComplete","createdAt","expiresAt"],"additionalProperties":false}}}},"409":{"description":"The connection must be reconciled before it can be edited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/reconciliation/apply":{"post":{"tags":["Connectors"],"summary":"Apply an exact grant replacement from one preview","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"previewId":{"type":"string","minLength":1},"grants":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1}}},"required":["agentId","operationRevisionIds"],"additionalProperties":false}}},"required":["previewId","grants"],"additionalProperties":false}}}},"responses":{"200":{"description":"Exact persisted grants and hosted authority synchronization state","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]},"authoritySync":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ready"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["status","reason"],"additionalProperties":false}]},"grants":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"operationRevisionIds":{"type":"array","items":{"type":"string","minLength":1}}},"required":["agentId","operationRevisionIds"],"additionalProperties":false}}},"required":["connectionId","reconciliationStatus","authoritySync","grants"],"additionalProperties":false}}}},"409":{"description":"The preview was consumed, expired, or superseded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/accessible":{"get":{"tags":["Connectors"],"summary":"List connections accessible to one owned agent","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"query"}],"responses":{"200":{"description":"Agent-scoped accessible connections","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","expired","revoked","pending","paused"]},"custody":{"type":"string","enum":["managed","self-host","external"]},"reconciliationStatus":{"type":"string","enum":["ready","migration_needs_reconcile"]}},"required":["connectionId","toolkit","label","status","custody","reconciliationStatus"],"additionalProperties":false}}},"required":["connections"],"additionalProperties":false}}}},"401":{"description":"A verified program credential is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/accessible/{connectionId}/operations":{"get":{"tags":["Connectors"],"summary":"List exact granted operation revisions for one connection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"connectionId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"query"}],"responses":{"200":{"description":"Exact agent-scoped operation revisions","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"operations":{"type":"array","items":{"type":"object","properties":{"operationRevisionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"toolkitVersion":{"type":"string","minLength":1},"capabilityClassification":{"type":"string","enum":["read","write","destructive"]},"retryPolicy":{"type":"string","enum":["never","provider_idempotency_key"]},"inputSchema":{"type":"object","additionalProperties":{}}},"required":["operationRevisionId","toolkit","operationSlug","toolkitVersion","capabilityClassification","retryPolicy","inputSchema"],"additionalProperties":false}}},"required":["connectionId","operations"],"additionalProperties":false}}}},"404":{"description":"Connection absent, ungranted, or owned by someone else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/executions":{"post":{"tags":["Connectors"],"summary":"Execute one exact connector operation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"connectionId":{"type":"string","minLength":1},"operationRevisionId":{"type":"string","minLength":1},"arguments":{"type":"object","additionalProperties":{}}},"required":["agentId","connectionId","operationRevisionId","arguments"],"additionalProperties":false}}}},"responses":{"200":{"description":"Brokered execution result with durable attempt identity","content":{"application/json":{"schema":{"type":"object","properties":{"logicalOperationId":{"type":"string","minLength":1},"attemptCount":{"type":"integer","minimum":1,"maximum":2},"result":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"data":{}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["cancelled"]},"code":{"type":"string","enum":["CANCELLED_BEFORE_DISPATCH"]},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["outcome_unknown"]},"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"],"additionalProperties":false}]}},"required":["logicalOperationId","attemptCount","result"],"additionalProperties":false}}}},"202":{"description":"Owner approval is required before execution","content":{"application/json":{"schema":{}}}},"403":{"description":"The principal lacks the exact grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/cli/executions":{"post":{"tags":["Connectors"],"summary":"Execute one exact connector operation from the CLI","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"connectionId":{"type":"string","minLength":1},"operationRevisionId":{"type":"string","minLength":1},"arguments":{"type":"object","additionalProperties":{}}},"required":["agentId","connectionId","operationRevisionId","arguments"],"additionalProperties":false}}}},"responses":{"200":{"description":"Brokered execution result with durable attempt identity","content":{"application/json":{"schema":{"type":"object","properties":{"logicalOperationId":{"type":"string","minLength":1},"attemptCount":{"type":"integer","minimum":1,"maximum":2},"result":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"data":{}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["cancelled"]},"code":{"type":"string","enum":["CANCELLED_BEFORE_DISPATCH"]},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["outcome_unknown"]},"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["status","code","message"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["unsupported"]},"reason":{"type":"string","minLength":1}},"required":["status","reason"],"additionalProperties":false}]}},"required":["logicalOperationId","attemptCount","result"],"additionalProperties":false}}}},"202":{"description":"Owner approval is required before execution","content":{"application/json":{"schema":{}}}},"403":{"description":"The principal lacks the exact grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/connectors/usage/agent":{"get":{"tags":["Connectors"],"summary":"List connector usage for one owned agent","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Agent-scoped connector usage page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"logicalOperationId":{"type":"string","minLength":1},"attemptIndex":{"type":"integer","exclusiveMinimum":0},"surface":{"type":"string","enum":["mcp","rest","cli","event"]},"actorKind":{"type":"string","enum":["operator","agent","program","event","runtime"]},"agentId":{"type":"string","minLength":1},"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"outcome":{"type":"string","enum":["success","error","cancelled","outcome_unknown","unsupported"]},"errorCode":{"type":"string","minLength":1},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["logicalOperationId","attemptIndex","surface","actorKind","connectionId","toolkit","operationRevisionId","operationSlug","payer","startedAt"],"additionalProperties":false}},"nextCursor":{"type":"string","minLength":1}},"required":["items"],"additionalProperties":false}}}}}}},"/api/connectors/usage/operator":{"get":{"tags":["Connectors"],"summary":"List operator-scoped connector usage","parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"connectionId","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Owner-scoped connector usage page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"logicalOperationId":{"type":"string","minLength":1},"attemptIndex":{"type":"integer","exclusiveMinimum":0},"surface":{"type":"string","enum":["mcp","rest","cli","event"]},"actorKind":{"type":"string","enum":["operator","agent","program","event","runtime"]},"agentId":{"type":"string","minLength":1},"connectionId":{"type":"string","minLength":1},"toolkit":{"type":"string","minLength":1},"operationRevisionId":{"type":"string","minLength":1},"operationSlug":{"type":"string","minLength":1},"payer":{"type":"string","enum":["operator_byo","dorkos_managed"]},"outcome":{"type":"string","enum":["success","error","cancelled","outcome_unknown","unsupported"]},"errorCode":{"type":"string","minLength":1},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["logicalOperationId","attemptIndex","surface","actorKind","connectionId","toolkit","operationRevisionId","operationSlug","payer","startedAt"],"additionalProperties":false}},"nextCursor":{"type":"string","minLength":1}},"required":["items"],"additionalProperties":false}}}}}}},"/api/relay/bindings/{id}/move":{"post":{"tags":["Relay"],"summary":"Re-point an existing binding to a different agent","description":"Moves the binding in place — same id, same chatId, new agentId — the one narrow exception to \"bindings are re-created, not re-pointed.\" Clears the binding's stale session mappings so the next inbound message starts fresh under the new agent.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveBindingRequest"}}}},"responses":{"200":{"description":"The re-pointed binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingResponse"}}}},"400":{"description":"Unknown agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/unclaimed-chats":{"get":{"tags":["Relay"],"summary":"List chats with no binding to route them (default: pending)","description":"Chats an adapter heard from with no binding — the durable, damped record of what used to be a silent drop. Carries only sender identity metadata, never a message body.","parameters":[{"schema":{"type":"string","enum":["pending","claimed","ignored","blocked"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Matching unclaimed chats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnclaimedChatListResponse"}}}}}}},"/api/relay/unclaimed-chats/{id}/claim":{"post":{"tags":["Relay"],"summary":"Claim an unclaimed chat onto an agent","description":"Creates a binding through the same uniqueness-checked path a manual binding create uses — a race against a manually created binding for the same chat 409s identically. `bridge: true` is the claim card's primary action, \"Answer in a channel\": claim, binding, and bridge in one call through the same lifecycle \"Bridge to a channel\" uses. The claim always succeeds when the response is 201; a failed bridge step is reported as `bridgeError` rather than failing the claim.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimUnclaimedChatRequest"}}}},"responses":{"201":{"description":"The binding created from this claim, optionally bridged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimUnclaimedChatResponse"}}}},"400":{"description":"Unknown agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown unclaimed chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The chat was bound by something else in the meantime","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/unclaimed-chats/{id}/ignore":{"post":{"tags":["Relay"],"summary":"Mute an unclaimed chat (idempotent)","description":"Future sightings still bump counters, silently — the chat never resurfaces.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Muted"},"404":{"description":"Unknown unclaimed chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/relay/unclaimed-chats/{id}/block":{"post":{"tags":["Relay"],"summary":"Block an unclaimed chat (idempotent)","description":"Drops all future traffic from this chat recordless — no further row writes.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Blocked"},"404":{"description":"Unknown unclaimed chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/approvals/pending":{"get":{"tags":["Approvals"],"summary":"List approvals waiting on a person","description":"Approvals an agent has requested and nobody has decided yet, oldest first. Expired requests are excluded, and no response here ever carries token material.","responses":{"200":{"description":"Pending approvals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalsResponse"}}}}}}},"/api/approvals/{id}/grant":{"post":{"tags":["Approvals"],"summary":"Allow the requested action","description":"$101","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantApprovalBody"}}}},"responses":{"200":{"description":"Approval granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDecisionResponse"}}}},"401":{"description":"Login is enabled and the caller is not signed in (`AUTH_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Refused: an agent cannot decide (`AGENT_CANNOT_DECIDE`), and neither can the caller holding the approval token (`REQUESTER_CANNOT_DECIDE`). For `standing: true`, also when login is off (`standing_grants_require_login`) or the caller has no session cookie (`operator_cookie_required`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already decided; or `standing: true` was asked for while standing permissions are switched off (`STANDING_GRANTS_DISABLED`), or for an approval that recorded no agent path, so there is no agent to stop asking about (`APPROVAL_HAS_NO_AGENT`). Nothing is granted in the last two cases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Expired before it was decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The one-time yes was recorded but the permission was not (`STANDING_PERMISSION_NOT_RECORDED`). The two are separate writes; this answer carries `approvalId` and `outcome` so a caller can tell it apart from \"nothing happened\" — retrying the whole call would answer 409, which reads like the permission exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandingPermissionNotRecordedResponse"}}}}}}},"/api/approvals/{id}/deny":{"post":{"tags":["Approvals"],"summary":"Refuse the requested action","description":"Denies a pending approval, with an optional reason the requester sees. Who may decide is exactly as for grant: no agent identity, no approval token, and an authenticated user when local login is enabled.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DenyApprovalBody"}}}},"responses":{"200":{"description":"Approval denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDecisionResponse"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Login is enabled and the caller is not signed in (`AUTH_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Refused: an agent cannot decide (`AGENT_CANNOT_DECIDE`), and neither can the caller holding the approval token (`REQUESTER_CANNOT_DECIDE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Expired before it was decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/approvals/grants":{"get":{"tags":["Approvals"],"summary":"List live standing permissions","description":"The standing permissions that are live right now: which agent, which action, and when each one runs out. A permission nobody can find is a dark pattern, so this is the list the DorkOS app shows in both places it offers to end one. Expiry is applied here rather than left to a sweep, so a permission whose window has closed is already gone from this list.\n\nAuthorized like deciding an approval, NOT like reading the pending list, and the difference is deliberate. A pending card is meant to be agent-readable. This list is prospective: it says which irreversible action will go through silently right now and the minute the window shuts, and it names other agents' pairings. So a caller presenting an agent identity or an approval token is refused.\n\nIt carries what the DorkOS app renders and nothing more. Who opened each permission, when, under which posture, and which card it came from are recorded in the `approval.grant_created` Activity event instead, which is where an audit question belongs.","responses":{"200":{"description":"Live standing permissions, soonest to expire first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandingPermissionsResponse"}}}},"401":{"description":"Login is enabled and the caller is not signed in (`AUTH_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Refused: an agent cannot read this (`AGENT_CANNOT_DECIDE`), and neither can the caller holding the approval token (`REQUESTER_CANNOT_DECIDE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/approvals/grants/{id}":{"delete":{"tags":["Approvals"],"summary":"End one standing permission","description":"Ends a standing permission, so DorkOS asks again before the next time that agent runs that action. It does not undo anything that already ran.\n\nEnding one NARROWS what an agent may do, so it needs no session cookie — unlike opening one. It still needs proof of a person in the same sense deciding an approval does: a caller presenting an agent identity or an approval token is refused in every posture. A second click answers 404, so the moment a permission ended cannot be rewritten.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The permission was ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeStandingPermissionResponse"}}}},"401":{"description":"Login is enabled and the caller is not signed in (`AUTH_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Refused: an agent cannot decide (`AGENT_CANNOT_DECIDE`), and neither can the caller holding the approval token (`REQUESTER_CANNOT_DECIDE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No permission is live under that id (`UNKNOWN_STANDING_PERMISSION`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms":{"get":{"tags":["Rooms"],"summary":"List rooms visible to the caller","description":"A human sees every room; an agent presenting a valid `X-DorkOS-Agent` sees only rooms it belongs to, and one presenting a token this machine cannot verify is refused with 401 rather than shown the operator’s list. `unreadCount` is null for a room the caller is not a member of, and `participants` is null for anything that is not a direct message.","parameters":[{"schema":{"$ref":"#/components/schemas/RoomKind"},"required":false,"name":"kind","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"includeArchived","in":"query"}],"responses":{"200":{"description":"Rooms, newest activity first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Rooms"],"summary":"Open a channel or a DM","description":"The room and its seeded roster are written in one transaction, including any agent named by `agentPaths` — so creating a DM is one call and a failed resolve leaves no room behind. A DM may name any number of agents; one gives a one-to-one conversation and several give a group. **Creating a DM is idempotent on its member set**: when a direct message already holds exactly these authors (the creator included, order irrelevant, neither a superset nor a subset), that room is returned instead of a second one being minted, and an archived match is un-archived first. The existing room keeps its own title and its place in the activity order — opening a conversation is not activity in it. Read the status to tell the two apart: **201** means a room was created, **200** means one was already there. The body is identical either way, so the status is the only signal.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoomRequest"}}}},"responses":{"200":{"description":"The direct message that already held exactly these members, returned instead of a second one being created (un-archived first if it was archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomWithRoster"}}}},"201":{"description":"A new room, with its roster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomWithRoster"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"An agent caller tried to seed the room with a SECOND agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A live channel already holds that slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/threads":{"get":{"tags":["Rooms"],"summary":"List threads the caller takes part in, across every room","description":"Every thread the caller started or replied in, newest activity first, with the room it lives in, an excerpt of its opening message, its reply count and how many of those replies are above the caller's read cursor. Participation selects a thread and the room's roster permits it: the caller wrote the root or one of the replies, AND is on that room's roster today — so a room they have been removed from contributes no threads at all. There is no follow list and nothing here is stored; the list is derived from the room log on every read. `unreadCount` shares the room's single `(member, room)` cursor, so opening a room clears its threads' counts along with its own.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Threads, newest activity first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}":{"get":{"tags":["Rooms"],"summary":"Get one room with its roster","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The room and its members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomWithRoster"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Rooms"],"summary":"Update a room title, topic, or archived flag","description":"Archiving a channel releases its slug. Un-archiving reclaims it, and is refused with 409 when another channel took it meanwhile.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoomRequest"}}}},"responses":{"200":{"description":"The updated room with its roster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomWithRoster"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Un-archiving would collide with a live channel holding the slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/sessions":{"get":{"tags":["Rooms"],"summary":"Where each of a room's agents does its work","description":"One `authorId → sessionId` pair per agent that has answered in this room, and nothing else — no session content, no working directory, no status. The narrowness is the point: this exists so a DorkOS client can turn \"Meeting Notes is working on it\" into a link you can follow, and a route that answered more would be a second way to read a session, reached through a room. A room the caller cannot see answers 404, exactly as reading the room does. **Only a person may ask** — an agent enumerating its room-mates' sessions is arbitration this domain has declined, so a caller whose `X-DorkOS-Agent` token resolves to a live agent is refused 403 `PEOPLE_ONLY`, and one whose token does not resolve is refused 401 before the room is looked up at all. A revoked agent is still an agent.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The bindings, one per agent that has answered here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomSessionsResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller presented an agent identity, which may not ask this (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/entries":{"get":{"tags":["Rooms"],"summary":"Read a page of room history","description":"Oldest-first within the page. Page backwards with `before=`. The room log is never trimmed, so any page remains readable. **The page is self-describing about threads**: a thread is a relation between entries rather than a room of its own, so a reply is only legible as a reply while the entry heading its thread is loaded beside it — and a thread outlives the 50-entry window it started in. `threadRoots` carries the roots this page replies to that the page itself does not hold, so nobody has to ask twice. They are context, never part of the page: each sits below the oldest entry in `entries`, which is where a `before=` cursor is read from.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Return entries with seq < this."},"required":false,"description":"Return entries with seq < this.","name":"before","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of entries, and the thread roots it points at outside itself","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomEntryListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Rooms"],"summary":"Post to a room (trigger-only)","description":"Returns 202 with the entry identity only. The entry itself reaches every reader — including the poster — over `GET /api/rooms/{id}/events`, mirroring `POST /api/sessions/{id}/messages` (ADR-0264). The author is resolved server-side from the caller identity and is never read from the body — an agent presenting a valid `X-DorkOS-Agent` posts as itself, and one presenting a token this machine cannot verify is refused with 401 rather than posting as the operator. Every agent member the post addresses is then triggered, bounded by the cascade guard; their replies arrive on the same stream.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostToRoomRequest"}}}},"responses":{"202":{"description":"Accepted; delivery rides the room SSE stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostToRoomResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/export":{"get":{"tags":["Rooms"],"summary":"Export a room's whole history as a JSONL file","description":"$102","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The export, one JSON object per line","headers":{"Content-Disposition":{"schema":{"type":"string","description":"Always `attachment; filename=\"room--.jsonl\"`. Part of the contract, not a courtesy: `dorkos room export` reads the name out of it when no `--out` is given, so a client may rely on the filename being present and quoted. The date is the EXPORT's, so two exports of one room a month apart do not overwrite each other."},"required":true,"description":"Always `attachment; filename=\"room--.jsonl\"`. Part of the contract, not a courtesy: `dorkos room export` reads the name out of it when no `--out` is given, so a client may rely on the filename being present and quoted. The date is the EXPORT's, so two exports of one room a month apart do not overwrite each other."},"X-Content-Type-Options":{"schema":{"type":"string","description":"Always `nosniff` — this is a file of other people's words."},"required":true,"description":"Always `nosniff` — this is a file of other people's words."}},"content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/RoomExportLine"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/attachments":{"post":{"tags":["Rooms"],"summary":"Upload files into a room, before the message that carries them","description":"$103","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"}}},"required":["files"]}}}},"responses":{"200":{"description":"Stored; ids to reference in the post that follows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomAttachmentUploadResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Only a person can attach a file; an agent caller is refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"A file is larger than the configured limit, refused while still being read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"A file's type is not in the configured allowlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/attachments/{attachmentId}":{"get":{"tags":["Rooms"],"summary":"Download one of a room’s files","description":"$104","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"attachmentId","in":"path"}],"responses":{"200":{"description":"The bytes, typed and dispositioned by what they were verified to be","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Not modified — the `If-None-Match` ETag still matches"},"400":{"description":"The id could never name a stored file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such file, or not yours to read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/entries/{entryId}/reactions":{"post":{"tags":["Rooms"],"summary":"React to an entry, or take a reaction back","description":"$105","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"entryId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleReactionRequest"}}}},"responses":{"202":{"description":"Accepted; the entry's new reaction set rides the room SSE stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleReactionResponse"}}}},"400":{"description":"Validation error, including anything that is not a single emoji","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, not a member of it, or no such entry in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"This agent has spent its hourly reaction allowance in this room (`REACTION_RATE_LIMITED`). People are never counted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/members":{"post":{"tags":["Rooms"],"summary":"Add a member to a room","description":"Add by `authorId`, or by `agentPath` to mint an agent author on first use. `responseMode` is seeded from the room kind when omitted. Operator-only: an agent that could widen a room-mate addressing could drive replies nobody asked for.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRoomMemberRequest"}}}},"responses":{"201":{"description":"The stored membership with its author resolved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomRosterEntry"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Only the local human may change a roster; an agent caller is refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, no such author, or no agent registered at that path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/members/{authorId}":{"patch":{"tags":["Rooms"],"summary":"Change a member's per-room response mode","description":"Operator-only. `responseMode` decides when an agent answers without being addressed, so an agent able to turn it up on a room-mate could manufacture a conversation.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"authorId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMembershipRequest"}}}},"responses":{"200":{"description":"The updated membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomRosterEntry"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Only the local human may change a roster; an agent caller is refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or not a member of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Rooms"],"summary":"Remove a member from a room","description":"Operator-only. Also drops that member's per-room session binding.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"authorId","in":"path"}],"responses":{"204":{"description":"Member removed"},"403":{"description":"Only the local human may change a roster; an agent caller is refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or not a member of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/authors/{authorId}/handle":{"patch":{"tags":["Rooms"],"summary":"Set or clear an author's handle","description":"A handle is what somebody types after an `@` to reach exactly one author: lowercase, 2–32 characters of `[a-z0-9._-]`, starting and ending alphanumeric, and unique across this install (case-folded). The server normalizes what it is given, so a client that skipped its own check cannot store something the grammar forbids, and an empty string clears the handle. **Human-initiated only** — any caller presenting `X-DorkOS-Agent` is refused, 403 when the token resolves to a live agent and 401 when it does not. There is no MCP tool and no capability for this: an agent able to rename itself in a loop would grow the tombstone table a row at a time forever, and removing the mechanism beats throttling it. A released handle stays reserved to the author who gave it up; they may take it back, and nobody else may take it at all.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"authorId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAuthorHandleRequest"}}}},"responses":{"200":{"description":"The author, with its handle as stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorRef"}}}},"400":{"description":"The handle fails the grammar (`INVALID_HANDLE`), or the body is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"An agent caller tried to change a handle (`OPERATOR_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No author carries that id (`MEMBER_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The handle is live on another author (`HANDLE_TAKEN`), or reserved to one — a handle they released, or one of the seeded broadcast words `everyone`/`here`/`channel` (`HANDLE_RESERVED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/threads":{"post":{"tags":["Rooms"],"summary":"Reply inside a thread","description":"A thread is a relation between entries in this room, not a room of its own, so there is nothing to create first: this posts the first reply and every later one. The reply keeps the room roster, the room read cursor and the room budget, and answers to the same rules any post does — the caller must be a member, and an archived room refuses. One level only: a reply whose root is itself a reply is refused with 400 (`NESTED_THREAD`). Trigger-only, like `POST /api/rooms/{id}/entries`: 202 with the entry identity, while the entry itself rides the room event stream to every reader.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostThreadReplyRequest"}}}},"responses":{"202":{"description":"Accepted; the entry reaches readers over the room event stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostToRoomResponse"}}}},"400":{"description":"Validation error, or the root entry is itself a reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, not a member of it, or no such entry in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/halt":{"post":{"tags":["Rooms"],"summary":"Stop every turn running in a room","description":"A control action, not a message. It interrupts every in-flight agent turn in the room, drops the working indicators, and writes one `halted` notice everyone in the room can see. Stopping is NEVER inferred from message text: a person who sends the word \"stop\" as a message has sent a message, and the agents answer it like any other. Takes no body. Only a person may call it — an agent stopping its room-mates would be arbitration this domain has declined — so a live agent is refused 403 and a caller whose agent token does not verify is refused 401. Allowed on an archived room, unlike every other write here: archiving stops a room gaining messages, and a turn that was already running is still running.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"How many in-flight turns were interrupted; 0 when the room was idle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HaltRoomResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not a person; agents do not stop each other","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or not a member of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/halt/{authorId}":{"post":{"tags":["Rooms"],"summary":"Stop one agent in a room","description":"A control action, not a message, scoped to one agent. It interrupts that agent’s in-flight turn here, throws away the answer if the turn streams one anyway, drops the messages it had not read yet in this room, releases its working indicator, and writes one `halted` notice naming who stopped whom. Every other agent in the room keeps working. Takes no body. Only a person may call it — a live agent is refused 403 and a caller whose agent token does not verify is refused 401. Allowed on an archived room, like the room-wide stop.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"authorId","in":"path"}],"responses":{"200":{"description":"Whether a turn was interrupted: 1, or 0 when the agent was not running one here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HaltRoomResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not a person; agents do not stop each other","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, not a member of it, or no such agent on its roster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/holds/{authorId}/promote":{"post":{"tags":["Rooms"],"summary":"Ask for this room to be answered first","description":"One agent is one working directory, so a message addressed to an agent that is mid-turn in another room waits rather than being refused. This asks for THIS room to be the next one that agent answers. It REORDERS and never preempts: the blocking turn is untouched, nothing is interrupted, and the promoted message still waits for the agent to be free — a room that is passed over is next after that. Takes no body. Only a person may call it, exactly as with `halt` — a live agent is refused 403 and a caller whose agent token does not verify is refused 401. `{ \"promoted\": false }` means there was nothing waiting, which is a normal answer and not an error.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"authorId","in":"path"}],"responses":{"200":{"description":"Whether there was a waiting message to move to the front","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteHoldResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not a person; agents do not reorder each other","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or not a member of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/repo":{"post":{"tags":["Rooms"],"summary":"Give a room files of its own","description":"Creates the room’s own git repo — a home directory under the DorkOS data directory, an empty checkout whose branch is `main`, and a first `ROOM.md` committed as the person who asked. Takes no body: there is nothing to configure. **Only the person who owns this install may call it.** A caller presenting a valid `X-DorkOS-Agent` is refused 403 `OPERATOR_ONLY`, and one presenting a token this machine cannot verify is refused 401 — an agent that could give its own room a repo could hand itself a writable working directory nobody chose. A room the caller cannot see answers 404, the same way reading it does, so probing room ids tells 403 from 404 nothing. Calling it twice is safe: the second call answers 409 `ROOM_REPO_EXISTS` carrying the binding that is already there, and makes no second commit. With room files switched off in settings, 409 `ROOM_REPOS_DISABLED` — and nothing on disk is touched, so switching them back on returns everything.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"The room now has files of its own","content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"$ref":"#/components/schemas/RoomRepo"}},"required":["repo"]}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not the person who owns this install (`OPERATOR_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room already has files (`ROOM_REPO_EXISTS`, with the existing binding), or room files are switched off on this install (`ROOM_REPOS_DISABLED`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"repo":{"$ref":"#/components/schemas/RoomRepo"}},"required":["error","code"]}}}}}}},"/api/rooms/{id}/repo/status":{"get":{"tags":["Rooms"],"summary":"What a room’s files hold, and who has work that is not merged","description":"Where the room’s own copy is, and for every agent in the room, how far its working copy has run ahead of the room and how far behind, whether it has changes nobody committed, and whether any of that adds up to work the room has not got. Membership-gated exactly like reading the room’s history: a caller who is not on the roster gets the same 404 an unknown room gets, because a room id is not a capability — and seeing a room is not being in it, so the install’s owner is not exempt. It reports working-copy SLUGS and display names, never the directory an agent lives in. It reads only, and it does not queue behind a merge, so the answer may be one merge out of date — which is what a status always is.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The main tip, one row per agent branch, and the size against the caps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomRepoStatus"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room has no files (`NOT_A_PROJECT_ROOM`), or room files are switched off on this install (`ROOM_REPOS_DISABLED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/repo/merge":{"post":{"tags":["Rooms"],"summary":"Bring an agent’s work into the room","description":"Merges an agent’s branch into the room’s `main`, in the room’s own checkout, and posts one line in the room saying what landed. Merges into one room run **one at a time**: a second caller waits its turn, and is refused 429 `MERGE_IN_FLIGHT` only if the wait runs out. Every other refusal is a 409 and says which: `UNCOMMITTED_WORK` (the working copy has changes nobody committed), `BEHIND_MAIN` (the room has moved on — sync in your own copy first; the message says how far), `NOTHING_TO_MERGE`, `SYMLINK_ESCAPES_REPO` (a shortcut pointing outside the room’s files), `FILE_TOO_LARGE`, `REPO_CAP_EXCEEDED`, `MAIN_CHECKOUT_DIRTY` (something outside DorkOS wrote in the room’s own copy), `MERGE_CONFLICT` (nothing was changed). Nothing here can rewrite history: there is no force, no reset and no push on this surface or under it. Naming a `worktree` merges somebody else’s working copy and is owner-only (403 `OPERATOR_ONLY`); an agent omits it and merges its own.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeRoomRepoRequest"}}}},"responses":{"200":{"description":"The work is on the room’s `main`, and the room has been told once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomMergeResult"}}}},"400":{"description":"The request did not carry a summary anybody could read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Only the owner may merge somebody else’s working copy (`OPERATOR_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The merge was refused; `code` says which of the reasons above it was","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Another merge held the room’s queue and the wait ran out, or the queue was already full when this call arrived — both `MERGE_IN_FLIGHT`, with a message saying which. `Retry-After` carries the room’s own queue wait in seconds, so a client does not have to guess a backoff.","headers":{"Retry-After":{"description":"Seconds to wait before merging again.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/files":{"get":{"tags":["Rooms"],"summary":"List one directory of a room's own files","description":"$106","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"path","in":"query"}],"responses":{"200":{"description":"The directory, with per-entry provenance","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"commit":{"type":["string","null"]},"entries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"kind":{"type":"string","enum":["file","dir","symlink","submodule"]},"size":{"type":"integer","minimum":0},"lastCommit":{"type":["object","null"],"properties":{"sha":{"type":"string"},"author":{"type":"string"},"at":{"type":"string"},"subject":{"type":"string"}},"required":["sha","author","at","subject"]}},"required":["name","path","kind","size","lastCommit"]}}},"required":["path","commit","entries"]}}}},"400":{"description":"The path could have meant somewhere else (`ROOM_FILE_PATH_INVALID`), or names something that is not a directory (`ROOM_FILE_NOT_READABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller is not a member of it (`ROOM_NOT_FOUND`) — the same answer for both — or no such directory in the commit (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room has no files of its own, or room files are switched off on this install (`ROOM_HAS_NO_REPO`); or this machine has no git (`ROOM_REPO_GIT_UNAVAILABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/files/content":{"put":{"tags":["Rooms"],"summary":"Save one of a room's files","description":"$107","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1},"baseCommit":{"type":["string","null"],"pattern":"^[0-9a-f]{7,40}$"},"text":{"type":"string"}},"required":["path","baseCommit","text"]}}}},"responses":{"200":{"description":"The file is on the room’s `main`","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"commit":{"type":"string"},"size":{"type":"integer","minimum":0},"committed":{"type":"boolean"},"lastCommit":{"type":["object","null"],"properties":{"sha":{"type":"string"},"author":{"type":"string"},"at":{"type":"string"},"subject":{"type":"string"}},"required":["sha","author","at","subject"]}},"required":["path","commit","size","committed","lastCommit"]}}}},"400":{"description":"The path could have meant somewhere else, names something that is not a file, or the contents would not be text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent; only people save a room’s files (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller is not a member of it (`ROOM_NOT_FOUND`) — the same answer for both — or no such folder in the room’s files (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The file changed while it was being edited — `FILE_CHANGED`, and ONLY that code carries `conflict` — or the save was refused for one of the room-state reasons above (`MAIN_CHECKOUT_DIRTY`, `FILE_TOO_LARGE`, `REPO_CAP_EXCEEDED`, `ROOM_ARCHIVED`, `ROOM_HAS_NO_REPO`, `ROOM_REPOS_DISABLED`, `ROOM_REPO_GIT_UNAVAILABLE`), which answer with the code and the sentence alone. Switch on `code`, never on the presence of a field","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["FILE_CHANGED"]},"conflict":{"type":"object","properties":{"path":{"type":"string"},"commit":{"type":"string"},"lastCommit":{"type":["object","null"],"properties":{"sha":{"type":"string"},"author":{"type":"string"},"at":{"type":"string"},"subject":{"type":"string"}},"required":["sha","author","at","subject"]}},"required":["path","commit","lastCommit"]}},"required":["error","code","conflict"]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"413":{"description":"The request body is over the server’s 1 MB limit (`REQUEST_TOO_LARGE`). That limit is below the room’s own file cap, so a very large save meets this one first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Another write held the room’s queue and the wait ran out (`MERGE_IN_FLIGHT`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Rooms"],"summary":"Read one file from a room's files","description":"Gated identically to `GET /api/rooms/{id}/files`, and read from the same commit. The file is named by the `path` QUERY parameter rather than by a path segment, because a repo path holds slashes and a segment would mean encoding them on the way out and decoding them on the way in. **Three honest answers, not one plus two errors**: `text` carries the contents exactly as committed; `binary` is a file with a `NUL` byte in it — git's own test — whose bytes are never decoded into a string; `too-large` is a file over `rooms.repo.maxFileBytes`, checked against the size git already knows so an enormous file costs nothing to refuse. `size` is always the real size, whichever answer came back. A directory, a symlink and a submodule are each refused 400 `ROOM_FILE_NOT_READABLE` — **a link is listed but never followed**, so a symlink in the tree naming a path outside the room cannot be read through this. The contents are member-written: render them as untrusted text, never as a document with an origin.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"path","in":"query"}],"responses":{"200":{"description":"The file, or why its bytes are not here","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"commit":{"type":"string"},"size":{"type":"integer","minimum":0},"lastCommit":{"type":["object","null"],"properties":{"sha":{"type":"string"},"author":{"type":"string"},"at":{"type":"string"},"subject":{"type":"string"}},"required":["sha","author","at","subject"]},"body":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["text"]},"encoding":{"type":"string","enum":["utf-8"]},"text":{"type":"string"}},"required":["kind","encoding","text"]},{"type":"object","properties":{"kind":{"type":"string","enum":["binary"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["too-large"]},"maxBytes":{"type":"integer","exclusiveMinimum":0}},"required":["kind","maxBytes"]}]}},"required":["path","commit","size","lastCommit","body"]}}}},"400":{"description":"The path could have meant somewhere else (`ROOM_FILE_PATH_INVALID`), or names a folder, a link or another repository (`ROOM_FILE_NOT_READABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller is not a member of it (`ROOM_NOT_FOUND`) — the same answer for both — or no such file in the commit (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room has no files of its own, or room files are switched off on this install (`ROOM_HAS_NO_REPO`); or this machine has no git (`ROOM_REPO_GIT_UNAVAILABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/repo/main/repair":{"post":{"tags":["Rooms"],"summary":"Deal with changes somebody made outside DorkOS","description":"$108","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["commit"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["discard"]},"paths":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500}},"required":["action","paths"]}]}}}},"responses":{"200":{"description":"What was done, and whether the room’s files are clean now","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["commit","discard"]},"commit":{"type":["string","null"]},"paths":{"type":"integer","minimum":0},"clean":{"type":"boolean"}},"required":["action","commit","paths","clean"]}}}},"400":{"description":"Neither action was named, or a discard named no files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not the person who owns this install (`OPERATOR_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room (`ROOM_NOT_FOUND`), or a named path is not one of the changes waiting (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room has no files (`ROOM_HAS_NO_REPO`), its copy is on another branch (`MAIN_CHECKOUT_DIRTY`), or room files are switched off (`ROOM_REPOS_DISABLED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A merge or a save held the room’s queue and the wait ran out (`MERGE_IN_FLIGHT`) — a repair takes the same one lane every other write to a room’s files takes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas":{"get":{"tags":["Rooms"],"summary":"Read everything on a room's shared canvas","description":"The room's own table: the documents its members — people and agents alike — have put in front of each other. Pinned first, then most recently active. Content travels with each document, because a viewer that holds the row has to be able to draw it; what does NOT travel is a file's contents, which each viewer reads through the file route it already uses. **The stream is how an app stays current, not this route**: a cold `GET /api/rooms/{id}/events` carries the whole table in its snapshot and every later change arrives as a `canvas` frame. This exists for agents, for tests, and for a cold read without a stream. It still answers for an ARCHIVED room — reads always do; it is writes that stop.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The room's canvas, pinned first then most recently active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocumentListResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Rooms"],"summary":"Put something on a room's canvas","description":"Opens a document as YOU — the author is resolved from the request and never sent. Content with a natural identity (a file path, a URL) DEDUPES: opening something that is already on the table refreshes that document rather than adding a second tab beside it, which is what makes the canvas a table rather than a pile. `json` and `widget` have no such identity, so every open of one is a fresh document. Past twelve unpinned documents the least recently active is dropped to make room, and every viewer is told. Refused on an archived room.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenCanvasDocumentRequest"}}}},"responses":{"201":{"description":"The document, as every viewer now has it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived, or somebody else is editing the document this would have refreshed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas/{documentId}":{"get":{"tags":["Rooms"],"summary":"Read one document on a room’s canvas","description":"One row, content included. A document id from ANOTHER room answers exactly as one that never existed, so an id is never a way to read across rooms.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Rooms"],"summary":"Change one document on a room’s canvas","description":"Three independent changes, any of which may be omitted: replace what the document shows, pin or unpin it, and move it to the front of the list. **`activate` changes the ORDER and nobody's open tab.** A shared canvas that yanked everyone's view when somebody clicked would be the pixel version of interrupting, so ordering on the server is not a remote-control verb. Refused on an archived room, and refused while another member is editing the document.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCanvasDocumentRequest"}}}},"responses":{"200":{"description":"The document, as every viewer now has it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived, or somebody else is editing this document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Rooms"],"summary":"Take a document off a room’s canvas","description":"The row is deleted rather than marked closed, and every viewer is told to drop it. Nothing needs a tombstone: a viewer that reconnects hydrates the whole table from the room snapshot, so a close it missed corrects itself. Refused on an archived room.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"204":{"description":"Closed"},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas/{documentId}/editing":{"post":{"tags":["Rooms"],"summary":"Say you are editing a canvas document, or that you have stopped","description":"While you hold this, an agent's change to the same document is HELD rather than applied, and the agent is told it was held instead of being told it succeeded. Refresh it about every fifteen seconds while an editor is focused; it lapses on its own about forty-five seconds after the last refresh, so a browser that crashed mid-edit cannot leave a document nobody can touch. Send `{\"editing\": false}` on save, on close, and when you look away without changing anything.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEditingRequest"}}}},"responses":{"200":{"description":"Who holds the lock now, and when it lapses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEditingResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived, or somebody else already holds this lock","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas/{documentId}/thread":{"post":{"tags":["Rooms"],"summary":"Open a canvas document’s discussion, or re-open it","description":"The first call posts one message from the room naming the document and records which message heads the discussion; every call after that hands back the discussion that is already there and posts nothing. So two people pressing \"Discuss\" at the same moment — or the same person pressing it next week, on another device — all end up in one conversation. It wakes nobody: the message addresses no one and starts no agent’s turn, exactly as putting the document on the table did. Replies are ordinary thread replies.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"The discussion was already open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasThreadResponse"}}}},"201":{"description":"The discussion was opened by this call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasThreadResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/follow":{"put":{"tags":["Rooms"],"summary":"Follow somebody’s browser in this room, or say you still are","description":"While you follow somebody, your Browser tab goes where theirs goes. Call this again about every ten seconds to say you are still there: a claim nobody restates lapses after thirty, which is what makes a closed tab, a crashed browser and a lost connection the same event. Following somebody new replaces whoever you were following — a panel can only be in one place. The person you follow is told, and starts sharing their position only then, so a room where nobody follows anybody carries nothing extra at all.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowRoomMemberRequest"}}}},"responses":{"204":{"description":"Following"},"400":{"description":"The request named you (`CANNOT_FOLLOW_YOURSELF`), or was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent, which cannot follow or be followed (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"This machine is already holding as many claims as it will (`TOO_MANY_FOLLOWERS`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Rooms"],"summary":"Stop following whoever you were following here","description":"Answers the same way whether or not there was anything to stop, so pressing the toggle off twice — or a page closing after its claim already lapsed — is not an error. The person you were following is told, and goes quiet unless somebody else is still following them.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Stopped"},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent, which cannot follow or be followed (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/follow/view":{"post":{"tags":["Rooms"],"summary":"Say where you are looking, for whoever is following you","description":"Send at most once every 250 ms, and only while somebody is following you. It carries which document you are on, the page your browser is showing and how far down you have scrolled — never anything that is IN the page. The answer says whether anybody was following: `false` means stop sending, which is how a tab that missed the \"nobody is following you any more\" message goes quiet on its own.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRoomViewRequest"}}}},"responses":{"200":{"description":"Whether anybody was following, and the position therefore passed on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRoomViewResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent, which cannot follow or be followed (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas/{documentId}/diff":{"get":{"tags":["Rooms"],"summary":"Read the two copies of the file behind a worktree diff","description":"$109","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"Both copies, and the fingerprint a later write must carry back","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"The file, relative to both copies."},"base":{"type":"string","description":"The room’s own copy, or the empty string for a file this work adds."},"current":{"type":"string","description":"The member’s working copy, as it is on disk right now."},"currentHash":{"type":"string","description":"SHA-256 of `current`; a write must carry it back."}},"required":["path","base","current","currentHash"]}}}},"400":{"description":"The document is not a review of somebody’s working copy, or its tree or path is not one this room keeps (`CANVAS_ACTION_NOT_AVAILABLE_IN_A_ROOM`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent; only people review somebody else’s working copy (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller is not a member of it (`ROOM_NOT_FOUND`) — the same answer for both — no such document on this room’s canvas (`CANVAS_DOCUMENT_NOT_FOUND`), or the file is not in that working copy any more (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"This room has no files of its own (`NOT_A_PROJECT_ROOM`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Rooms"],"summary":"Put a reviewed file back in the member’s working copy","description":"How turning a hunk down lands: the whole file, conditional on the hash the diff was computed against. A file the agent changed in between answers `ok: false` carrying what it holds now — a conflict is control flow, and the screen recomputes rather than clobbering work that carried on. **People only** (403 `PEOPLE_ONLY`), on the same instrument `PUT /:id/files/content` uses: this writes into a colleague’s checkout, and an agent doing that leaves that colleague dirty — the state their own merge then refuses. Membership is asked first, so a non-member still gets 404. Any member who is a person may send a hunk back; only the owner may merge. Archived rooms refuse it 409, like every other canvas write.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"expectedHash":{"type":"string","minLength":1}},"required":["content","expectedHash"]}}}},"responses":{"200":{"description":"What was written, or what the file holds now","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"hash":{"type":"string"}},"required":["ok","hash"]},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"conflict":{"type":"object","properties":{"currentHash":{"type":"string"},"currentContent":{"type":"string"}},"required":["currentHash","currentContent"]}},"required":["ok","conflict"]}]}}}},"400":{"description":"The body is not a valid request, or the document is not a review of a working copy this room keeps (`CANVAS_ACTION_NOT_AVAILABLE_IN_A_ROOM`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent; only people review somebody else’s working copy (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, or the caller is not a member of it (`ROOM_NOT_FOUND`) — the same answer for both — no such document on this room’s canvas (`CANVAS_DOCUMENT_NOT_FOUND`), or the file is not in that working copy any more (`ROOM_FILE_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The room is archived (`ROOM_ARCHIVED`), or it has no files of its own (`NOT_A_PROJECT_ROOM`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/canvas":{"get":{"tags":["Sessions"],"summary":"Everything on this session’s canvas","description":"The documents open in this session's right panel, pinned first then most recently active — the same table on every device you open the session on. **The stream is how an app stays current, not this route**: a cold `GET /api/sessions/{id}/events` carries the whole canvas in its snapshot and every later change arrives as a `canvas` event. This exists for a cold read without a stream.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The session’s canvas, pinned first then most recently active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocumentListResponse"}}}},"400":{"description":"That is not a session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Sessions"],"summary":"Put something on this session’s canvas","description":"Content with a natural identity (a file path, a URL) DEDUPES: opening something already on the canvas refreshes that document rather than adding a second tab beside it, so two windows of one session land on one document. `json` and `widget` have no such identity, so every open of one is a fresh document. Past twelve unpinned documents the least recently active is dropped, and every window is told.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenCanvasDocumentRequest"}}}},"responses":{"201":{"description":"The document, as every window now has it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"400":{"description":"That is not a session id, or the body is not a valid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"That id names no session this server knows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Somebody is editing the document this would have refreshed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/canvas/{documentId}":{"get":{"tags":["Sessions"],"summary":"Read one document on this session’s canvas","description":"One row, content included. A document id from another session answers exactly as one that never existed, so an id is never a way to read across sessions.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"400":{"description":"That is not a session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such document on this canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Sessions"],"summary":"Change one document on this session’s canvas","description":"Three independent changes, any of which may be omitted: replace what the document shows, pin or unpin it, and move it to the front of the list.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCanvasDocumentRequest"}}}},"responses":{"200":{"description":"The document, as every window now has it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasDocument"}}}},"400":{"description":"That is not a session id, or the body is not a valid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such document on this canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Sessions"],"summary":"Take a document off this session’s canvas","description":"The row is deleted and every window of this session is told to drop it. Nothing needs a tombstone: a window that reconnects hydrates the whole canvas from the session snapshot, so a close it missed corrects itself.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"responses":{"204":{"description":"Closed"},"400":{"description":"That is not a session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such document on this canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/canvas/{documentId}/editing":{"post":{"tags":["Sessions"],"summary":"Say you are editing a canvas document, or that you have stopped","description":"While you hold this, the agent's change to the same document is HELD rather than applied, and the agent is told it was held instead of being told it succeeded. Refresh it about every fifteen seconds while an editor is focused; it lapses on its own about forty-five seconds after the last refresh, so a browser that crashed mid-edit cannot leave a document nobody can touch.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEditingRequest"}}}},"responses":{"200":{"description":"Who holds the lock now, and when it lapses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEditingResponse"}}}},"400":{"description":"That is not a session id, or the body is not a valid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"That agent identity could not be verified — its token may be revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"A session’s canvas is the person’s own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such document on this canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"This server has no canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/canvas/viewing":{"post":{"tags":["Rooms"],"summary":"Say which canvas document you are looking at","description":"Puts a small face on that document’s tab for everybody else looking at this room, and takes it off again when you send `{\"documentId\": null}`. **Nothing is written down.** The whole effect is one live-only frame on the room’s stream, so a reader who connects afterwards never learns it and a reconnect forgets it — a face left on a document somebody walked away from ten minutes ago would be worse than no face. Send it when the document you are looking at changes, and once with `null` on the way out. It answers for an archived room, because looking at one is allowed.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasViewingRequest"}}}},"responses":{"204":{"description":"Told the room"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such room, the caller may not see it, or no such document on its canvas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/rooms/{id}/events":{"get":{"tags":["Rooms"],"summary":"Durable room event stream (SSE, or WebSocket at the same path)","description":"$10a","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Resume cursor; ignored past the end of the log."},"required":false,"description":"Resume cursor; ignored past the end of the log.","name":"after","in":"query"},{"schema":{"type":"string","description":"Resume token `---`. Takes precedence over `after`; a token from another room, another server process, another seq space, or in the older generation-less format falls back to a cold connect."},"required":false,"description":"Resume token `---`. Takes precedence over `after`; a token from another room, another server process, another seq space, or in the older generation-less format falls back to a cold connect.","name":"resume","in":"query"}],"responses":{"200":{"description":"SSE stream: a RoomSnapshot frame on a cold connect, then RoomEvent frames. A WebSocket upgrade of the same path answers `101` with the identical sequence.","content":{"text/event-stream":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RoomSnapshot"},{"$ref":"#/components/schemas/RoomEntryEvent"},{"$ref":"#/components/schemas/RoomSignalEvent"},{"$ref":"#/components/schemas/RoomReactionEvent"},{"$ref":"#/components/schemas/RoomCanvasEvent"}]}}}},"404":{"description":"No such room, or the caller may not see it (an agent sees only its own rooms)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/read-cursors/{kind}/{id}":{"put":{"tags":["Read state"],"summary":"Advance the caller's read cursor in one thread","description":"$10b","parameters":[{"schema":{"$ref":"#/components/schemas/ReadCursorThreadKind"},"required":true,"name":"kind","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetReadCursorPositionRequest"}}}},"responses":{"200":{"description":"The cursor as it now stands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadCursor"}}}},"400":{"description":"Unknown `kind`, empty `id`, missing body, or a `lastReadSeq` that is not a non-negative integer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller resolved to an agent, which has no read state here (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Only for `kind: room` — no such room, or the caller is not a member of it. A `session` or `inbox` thread is never checked for existence, so those kinds cannot answer 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Read state"],"summary":"Read the caller's own position in one thread","description":"Where this person left off in one thread — the read half of the PUT, and the way a screen that has just opened knows where to draw the unread rule before any event arrives. A thread the caller has never read answers `{ \"cursor\": null }` with a 200, because never-read is the state every thread starts in rather than a missing resource; `null` is also distinct from a stored `0`, which is a thread read up to its own beginning. As with the write, the cursor is always the caller's own — there is no way to name a user — and an agent caller is refused with 403 `PEOPLE_ONLY`, or with 401 when its token does not verify.","parameters":[{"schema":{"$ref":"#/components/schemas/ReadCursorThreadKind"},"required":true,"name":"kind","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The caller's cursor, or null when they have never read this thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadCursorResponse"}}}},"400":{"description":"Unknown `kind` or empty `id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller resolved to an agent, which has no read state here (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/team":{"get":{"tags":["Team"],"summary":"List every identity on this install","description":"$10c","responses":{"200":{"description":"Roster envelope: the operator first, then people, then agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamRosterResponse"}}}},"500":{"description":"The roster itself could not be assembled (not a per-source failure)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/team/{memberId}/rooms":{"get":{"tags":["Team"],"summary":"List the rooms one roster member is in","description":"$10d","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"memberId","in":"path"}],"responses":{"200":{"description":"The member’s rooms, newest activity first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberRoomsResponse"}}}},"403":{"description":"The caller is an agent — a profile is read by people (`PEOPLE_ONLY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No member on this install carries that id (`MEMBER_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The membership read failed (`MEMBER_ROOMS_FAILED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/search":{"get":{"tags":["Search"],"summary":"Find messages by what was said in them","description":"$10e","parameters":[{"schema":{"type":"string"},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"source","in":"query"}],"responses":{"200":{"description":"Hits, best first, across every source this caller may read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"The request could not be read (`INVALID_SEARCH_QUERY`), or it named a source that does not exist (`UNKNOWN_SEARCH_SOURCE`). The `error` sentence says which field was wrong: `q` holds no WORD of at least the minimum length — counted over the words a search is split into, so `a,` and a string of spaces are refused exactly as `a` is — or `limit` was not a whole number above zero.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an agent token this machine could not verify (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/profile":{"patch":{"tags":["Profile"],"summary":"Set what the operator wants to be called","description":"$10f","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateRequest"}}}},"responses":{"200":{"description":"Saved. The name the roster will now show.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateResponse"}}}},"400":{"description":"The name is empty or longer than 80 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent — a person’s name is theirs to set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/profile/avatar":{"post":{"tags":["Profile"],"summary":"Set the operator's profile photo","description":"Multipart upload of a single image in the `avatar` field. The photo replaces whatever was there, in any format. Three refusals, all before anything is stored: over 2 MB (413), and anything whose MAGIC BYTES are not PNG, JPEG or WebP (415) — the filename and the `Content-Type` the client claims are not evidence, since both are written by whoever is uploading. SVG is therefore refused too, on purpose: it is a script vector, and a profile photo has no reason to be one. Nothing is re-encoded or resized. Only a person may call this; an agent presenting a valid identity token is refused (403), and one whose token this machine cannot verify is refused (401). The URL that comes back is written to BOTH the roster (`authors.image_url`) and the account record (`user.image`), so the two cannot disagree — and it is opaque: server-relative today, absolute the day a remote store backs it.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"avatar":{"type":"string","format":"binary"}},"required":["avatar"]}}}},"responses":{"200":{"description":"Stored. The URL to render and to keep.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileAvatarResponse"}}}},"400":{"description":"No file was attached, or the upload could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent — a profile photo is the operator’s to set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Larger than 2 MB, refused while still being read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"The bytes are not a PNG, JPEG or WebP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Profile"],"summary":"Remove the operator's profile photo","description":"Clears the stored file and both identity records. Idempotent: deleting a photo that is already gone succeeds, because the caller wanted it gone either way.","responses":{"204":{"description":"Gone"},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/profile/identities/{authorId}":{"post":{"tags":["Profile"],"summary":"Say that an account on another platform is you","description":"Records that one external identity — a Telegram or Slack account, stored as `platform:::` — is the operator themselves. What it buys is silence about your own words: a message you send your own agent from your own phone arrives as an ordinary person on that platform, so without this DorkOS raises a `dm.received` about it, and a `mention.received` for any `@` you type that spells one of your own handles. It is a claim about WHOSE WORDS those are and grants that account nothing on this install: every check that decides what a caller may do still keys on the local account you sign in as, so a linked identity gets no whole-room export, no roster writes and no wider search. Only the person who owns this install may call it — an agent is refused (403), and so is any second person — and only a `platform:` row may be claimed (400 otherwise), because claiming an agent would silence every message that agent sends. Idempotent.","parameters":[{"schema":{"type":"string","description":"The roster id of the identity to claim"},"required":true,"description":"The roster id of the identity to claim","name":"authorId","in":"path"}],"responses":{"204":{"description":"Recorded"},"400":{"description":"That identity is not somebody on another platform, so it cannot be claimed — an agent’s row, the system author, or a person on this machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent, or a person who does not own this install","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No identity by that id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Profile"],"summary":"Take that claim back","description":"The revocation half, gated identically. Idempotent: releasing an identity that was never claimed succeeds, because the caller wanted it unclaimed either way. Its messages notify the operator again from the very next one.","parameters":[{"schema":{"type":"string","description":"The roster id of the identity to claim"},"required":true,"description":"The roster id of the identity to claim","name":"authorId","in":"path"}],"responses":{"204":{"description":"Released"},"400":{"description":"That identity is not somebody on another platform, so it cannot be claimed — an agent’s row, the system author, or a person on this machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The caller presented an `X-DorkOS-Agent` token this machine could not verify — revoked, expired, or never minted here (`AGENT_IDENTITY_UNVERIFIED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is an agent, or a person who does not own this install","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No identity by that id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/profile/avatar/{id}":{"get":{"tags":["Profile"],"summary":"Serve an identity's profile photo","description":"Streams the stored image with `X-Content-Type-Options: nosniff`, a strong `ETag` derived from the content, and `Cache-Control: private, max-age=0, must-revalidate`. The `?v=` the stored URL carries is what makes a replaced photo appear at once without turning caching off; a matching `If-None-Match` answers 304. The id is opaque — one that could be read as a path is answered 404 rather than followed.","parameters":[{"schema":{"type":"string","description":"The identity id"},"required":true,"description":"The identity id","name":"id","in":"path"}],"responses":{"200":{"description":"The image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"The caller already has this exact photo"},"404":{"description":"That identity has no photo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/harness/status":{"get":{"tags":["Harness"],"summary":"What every agent tool does with every agent file in one project","description":"$110","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"projectPath","in":"query"}],"responses":{"200":{"description":"What this project’s agent-file sharing looks like right now, in any of the three states an HTTP caller can see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HarnessStatusResponse"}}}},"400":{"description":"`projectPath` was missing, blank or relative, or it named something that is not a directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`projectPath` resolves outside the directory boundary and outside `{dorkHome}/agents`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No directory there. Separated from `not-set-up` on purpose: a typo would otherwise read as a real folder that simply has nothing set up in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The read failed unexpectedly. The reason is logged, never echoed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/harness/sync":{"post":{"tags":["Harness"],"summary":"Share this project’s agent files with every agent tool it has turned on","description":"$111","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectPath":{"type":"string","minLength":1}},"required":["projectPath"]}}}},"responses":{"200":{"description":"What the sync did, and the status recomputed after it","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"object","properties":{"projectPath":{"type":"string"},"state":{"type":"string","enum":["ready","not-set-up","unreadable","unavailable"]},"detail":{"type":"string"},"computedAt":{"type":"string"},"enabled":{"type":"array","items":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]}},"notEnabled":{"type":"array","items":{"type":"object","properties":{"harness":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]},"why":{"type":"string","enum":["footprint","dorkos-runtime"]},"signal":{"type":"string"}},"required":["harness","why"]}},"clean":{"type":"boolean"},"counts":{"type":"object","properties":{"skills":{"type":"integer","minimum":0},"globalSkills":{"type":"integer","minimum":0},"drifted":{"type":"integer","minimum":0},"conflicts":{"type":"integer","minimum":0},"orphans":{"type":"integer","minimum":0},"adoptable":{"type":"integer","minimum":0},"pendingApproval":{"type":"integer","minimum":0}},"required":["skills","globalSkills","drifted","conflicts","orphans","adoptable","pendingApproval"]},"sweepPreview":{"type":"array","items":{"type":"string"}},"removals":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"rows":{"type":"array","items":{"type":"object","properties":{"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"provenance":{"type":"string","enum":["authored","installed","harness-native"]},"scope":{"type":"string","enum":["project","global"],"default":"project"},"name":{"type":"string"},"source":{"type":"string"},"adoptable":{"type":"boolean"},"cells":{"type":"object","properties":{"claude-code":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"codex":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"cursor":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"gemini":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"copilot":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"opencode":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]}}}},"required":["artifact","provenance","name","adoptable","cells"]}},"projectLevel":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["drop","warning","write","notice"]},"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"name":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"reason":{"type":"string"}},"required":["kind","artifact","name","reason"]}},"pendingApproval":{"type":"array","items":{"type":"object","properties":{"packageName":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"commandCount":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["unasked","refused","unreadable-config"]},"detail":{"type":"string"}},"required":["packageName","events","commandCount","reason"]}},"claudeOnly":{"type":"object","properties":{"root":{"type":"string"},"readAt":{"type":"string"},"unreadable":{"type":"string"},"mayBeOverridden":{"type":"boolean"},"plugins":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"marketplace":{"type":"string"},"repo":{"type":"string"},"settingsScope":{"type":"string","enum":["user","project"]},"offer":{"type":"string","enum":["install","add-source-then-install","unknown-source","no-package","sources-unreadable"]},"sourceUrl":{"type":"string"}},"required":["name","marketplace","settingsScope","offer"]}},"personalHookCommands":{"type":"integer","minimum":0},"unreadableParts":{"type":"array","items":{"type":"string","enum":["extraKnownMarketplaces","hooks"]}},"skippedEntries":{"type":"integer","minimum":0},"sourcesUnreadable":{"type":"string"}},"required":["root","readAt","mayBeOverridden","plugins","personalHookCommands","unreadableParts"]}},"required":["projectPath","state","computedAt","enabled","notEnabled","clean","counts","sweepPreview","removals","rows","projectLevel","pendingApproval"]},"applied":{"type":"integer","minimum":0},"swept":{"type":"array","items":{"type":"string"}},"removals":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"conflicts":{"type":"integer","minimum":0},"askedAbout":{"type":"array","items":{"type":"string"}}},"required":["status","applied","swept","removals","conflicts","askedAbout"]}}}},"400":{"description":"`projectPath` was missing, blank or relative, or it named something that is not a directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller named itself an agent or held an approval token, or `projectPath` resolves outside the directory boundary and outside `{dorkHome}/agents`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No directory there","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`code: \"harness_not_set_up\"` — this project has no `.agents/harness.manifest.json`, so there is nothing to share yet. `dorkos harness sync --fix` in the folder sets it up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The sync failed unexpectedly. The reason is logged, never echoed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/harness/adopt":{"post":{"tags":["Harness"],"summary":"Move one skill into `.agents/skills`, where every agent reads it","description":"$112","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectPath":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"claudeOnly":{"type":"boolean"}},"required":["projectPath","name"]}}}},"responses":{"200":{"description":"What the adopt did — or the one sentence saying why it did not — and the status recomputed after it","content":{"application/json":{"schema":{"type":"object","properties":{"moved":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"link":{"type":"object","properties":{"target":{"type":"string"}},"required":["target"]}},"required":["name","from","to"]}},"declared":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"reason":{"type":"string"}},"required":["name","path","reason"]}},"refusals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"source":{"type":"string"},"reason":{"type":"string"},"rule":{"type":"string","enum":["not-adoptable","hostile-path","room-seeded-name","target-exists","source-is-symlink","unreadable-frontmatter","not-on-allowlist","claude-only-wrong-root","cross-device","link-blocked","manifest-unwritable","canonical-layer-ignored","auto-adopt-not-permitted"]}},"required":["name","source","reason","rule"]}},"status":{"type":"object","properties":{"projectPath":{"type":"string"},"state":{"type":"string","enum":["ready","not-set-up","unreadable","unavailable"]},"detail":{"type":"string"},"computedAt":{"type":"string"},"enabled":{"type":"array","items":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]}},"notEnabled":{"type":"array","items":{"type":"object","properties":{"harness":{"type":"string","enum":["claude-code","codex","cursor","gemini","copilot","opencode"]},"why":{"type":"string","enum":["footprint","dorkos-runtime"]},"signal":{"type":"string"}},"required":["harness","why"]}},"clean":{"type":"boolean"},"counts":{"type":"object","properties":{"skills":{"type":"integer","minimum":0},"globalSkills":{"type":"integer","minimum":0},"drifted":{"type":"integer","minimum":0},"conflicts":{"type":"integer","minimum":0},"orphans":{"type":"integer","minimum":0},"adoptable":{"type":"integer","minimum":0},"pendingApproval":{"type":"integer","minimum":0}},"required":["skills","globalSkills","drifted","conflicts","orphans","adoptable","pendingApproval"]},"sweepPreview":{"type":"array","items":{"type":"string"}},"removals":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"rows":{"type":"array","items":{"type":"object","properties":{"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"provenance":{"type":"string","enum":["authored","installed","harness-native"]},"scope":{"type":"string","enum":["project","global"],"default":"project"},"name":{"type":"string"},"source":{"type":"string"},"adoptable":{"type":"boolean"},"cells":{"type":"object","properties":{"claude-code":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"codex":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"cursor":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"gemini":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"copilot":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]},"opencode":{"type":"object","properties":{"state":{"type":"string","enum":["native","projected","drifted","dropped","warned","conflict","pending-approval"]},"reason":{"type":"string"},"target":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["state"]}}}},"required":["artifact","provenance","name","adoptable","cells"]}},"projectLevel":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["drop","warning","write","notice"]},"artifact":{"type":"string","enum":["skill","instruction","hook","command","plugin","agent","rule","mcp","manifest"]},"name":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"reason":{"type":"string"}},"required":["kind","artifact","name","reason"]}},"pendingApproval":{"type":"array","items":{"type":"object","properties":{"packageName":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"commandCount":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["unasked","refused","unreadable-config"]},"detail":{"type":"string"}},"required":["packageName","events","commandCount","reason"]}},"claudeOnly":{"type":"object","properties":{"root":{"type":"string"},"readAt":{"type":"string"},"unreadable":{"type":"string"},"mayBeOverridden":{"type":"boolean"},"plugins":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"marketplace":{"type":"string"},"repo":{"type":"string"},"settingsScope":{"type":"string","enum":["user","project"]},"offer":{"type":"string","enum":["install","add-source-then-install","unknown-source","no-package","sources-unreadable"]},"sourceUrl":{"type":"string"}},"required":["name","marketplace","settingsScope","offer"]}},"personalHookCommands":{"type":"integer","minimum":0},"unreadableParts":{"type":"array","items":{"type":"string","enum":["extraKnownMarketplaces","hooks"]}},"skippedEntries":{"type":"integer","minimum":0},"sourcesUnreadable":{"type":"string"}},"required":["root","readAt","mayBeOverridden","plugins","personalHookCommands","unreadableParts"]}},"required":["projectPath","state","computedAt","enabled","notEnabled","clean","counts","sweepPreview","removals","rows","projectLevel","pendingApproval"]}},"required":["moved","declared","refusals","status"]}}}},"400":{"description":"`projectPath` was missing, blank or relative, `name` was missing or blank, or `projectPath` named something that is not a directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`code: \"operator_only_harness_adopt\"` — the caller named itself an agent or held an approval token — or `projectPath` resolves outside the directory boundary and outside `{dorkHome}/agents`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No directory there","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`code: \"harness_not_set_up\"` — this project has no `.agents/harness.manifest.json`, so there is nothing to move a skill within. `dorkos harness sync --fix` in the folder sets it up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The adopt failed unexpectedly. The reason is logged, never echoed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/notifications":{"get":{"tags":["Notifications"],"summary":"List notification history","description":"Newest first, cursor-paged. Filters are lenses, not a search. A caller that is not entitled to the operator view reads an empty list rather than a refusal, so a response never says that notifications exist.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"before","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agentId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sessionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"unread","in":"query"}],"responses":{"200":{"description":"One page of history, with the unfiltered unread count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListNotificationsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/notifications/{id}/read":{"patch":{"tags":["Notifications"],"summary":"Mark one notification read","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"How many rows moved, and the unread count after","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkNotificationsReadResponse"}}}},"403":{"description":"Only the operator may move read state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/notifications/read-all":{"post":{"tags":["Notifications"],"summary":"Mark every unread notification read","responses":{"200":{"description":"How many rows moved, and the unread count after","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkNotificationsReadResponse"}}}},"403":{"description":"Only the operator may move read state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/push/vapid-public-key":{"get":{"tags":["Notifications"],"summary":"Read the VAPID public key a browser needs to subscribe","description":"Generates this install’s keypair on the first call. Answers `key: null` when web push is unavailable here, so a client can say so instead of offering a button that fails.","responses":{"200":{"description":"The public key, or null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VapidPublicKeyResponse"}}}},"403":{"description":"Only the operator may see this install’s push setup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/push/subscriptions":{"get":{"tags":["Notifications"],"summary":"List the browsers DorkOS may push to","description":"Never returns an endpoint — only the push service’s hostname and the dates.","responses":{"200":{"description":"Every subscribed browser, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPushSubscriptionsResponse"}}}},"403":{"description":"Only the operator may list push devices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Notifications"],"summary":"Let DorkOS push to this browser","description":"Idempotent by endpoint, so a client may call it on every load to refresh keys the browser rotated without accumulating dead rows.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPushSubscriptionRequest"}}}},"responses":{"200":{"description":"The subscription as it now stands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPushSubscriptionResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Only the operator may subscribe a device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/push/subscriptions/{id}":{"delete":{"tags":["Notifications"],"summary":"Stop pushing to one browser","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"How many rows went away — 0 when it was already gone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePushSubscriptionResponse"}}}},"403":{"description":"Only the operator may remove a push device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/workspaces/scan":{"get":{"tags":["Workspaces"],"summary":"List the real checkouts on disk","description":"Read-only scan of the workspace root. Reports every git checkout found there — branch, uncommitted changes, ahead/behind, last commit — without writing to any of them. A checkout git cannot describe is reported with `readable: false` rather than dropped.","responses":{"200":{"description":"The scanned root and what it holds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorktreeScanResult"}}}},"500":{"description":"The scan could not run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/activity":{"get":{"tags":["Operator"],"summary":"List activity","description":"List DorkOS activity-feed events (agent, tasks, relay, config, system). Filter by categories (comma-separated), actorType, actorId, and a time window (before/since ISO timestamps); paginate with limit and the returned nextCursor.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"before","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categories","in":"query"},{"schema":{"$ref":"#/components/schemas/ActorType"},"required":false,"name":"actorType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"since","in":"query"}],"responses":{"200":{"description":"List activity result","content":{"application/json":{"schema":{}}}}}}},"/api/agents/{agentId}/mcp-servers":{"get":{"tags":["Mcp"],"summary":"List an agent’s managed MCP servers","description":"List the MCP servers DorkOS manages for an agent, each with its transport, enabled state, audit record, and — for a remote server — whether DorkOS holds a live sign-in for it (authStatus). A free read — use it before add/update/remove to see what is already configured.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"required":true,"description":"The id of the agent whose managed MCP servers this acts on.","name":"agentId","in":"query"}],"responses":{"200":{"description":"List an agent’s managed MCP servers result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServerView"}}}}}}},"post":{"tags":["Mcp"],"summary":"Add a managed MCP server to an agent","description":"Add an MCP server to an agent and enable it. This introduces a command (stdio) or remote endpoint (http/sse) that will run in the agent’s environment, so a person approves it first at a card showing the exact command/args/url. Rejects the reserved name \"dorkos\" and any name the agent already uses. If the added entry comes back with connection.authKind \"oauth2\", the server needs a sign-in: call the MCP sign-in tool for it immediately, in the same turn, rather than asking permission first — the person already approved this endpoint at the card above, and nothing leaves this machine until they open the sign-in link. Its tools are live on the next turn once they finish.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."},"connection":{"oneOf":[{"type":"object","properties":{"transport":{"type":"string","enum":["stdio"]},"command":{"type":"string","minLength":1},"args":{"type":"array","items":{"type":"string"},"default":[]},"env":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}}},"required":["transport","command"]},{"type":"object","properties":{"transport":{"type":"string","enum":["http"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]},{"type":"object","properties":{"transport":{"type":"string","enum":["sse"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]}],"description":"How to reach the server (stdio/http/sse)."},"enabled":{"type":"boolean","description":"Whether the server is enabled on add. Defaults to enabled (spec §4)."}},"required":["agentId","name","connection"]}}}},"responses":{"200":{"description":"Add a managed MCP server to an agent result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}/import":{"post":{"tags":["Mcp"],"summary":"Import a discovered MCP server into DorkOS management","description":"Bring a server DorkOS discovered in a project’s .mcp.json under DorkOS management: resolve its transport, then add it as an enabled, editable managed server. Routed through the same approval gate as add, because the imported entry will run in the agent’s environment. Rejects the reserved name \"dorkos\" and any name already managed; reports a clear error when no such discovered server can be resolved.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."}},"required":["agentId","name"]}}}},"responses":{"200":{"description":"Import a discovered MCP server into DorkOS management result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}":{"patch":{"tags":["Mcp"],"summary":"Update a managed MCP server","description":"Change a managed server’s transport and/or enabled state. Changing the transport introduces a new command/endpoint, so it is approved at a card showing the exact command/args/url, exactly like add.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."},"connection":{"oneOf":[{"type":"object","properties":{"transport":{"type":"string","enum":["stdio"]},"command":{"type":"string","minLength":1},"args":{"type":"array","items":{"type":"string"},"default":[]},"env":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}}},"required":["transport","command"]},{"type":"object","properties":{"transport":{"type":"string","enum":["http"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]},{"type":"object","properties":{"transport":{"type":"string","enum":["sse"]},"url":{"type":"string","format":"uri"},"headers":{"type":"object","properties":{},"default":{},"additionalProperties":{"type":"string"}},"authKind":{"type":"string","enum":["oauth2"]}},"required":["transport","url"]}],"description":"Replacement transport. Omit to leave the server’s transport unchanged."},"enabled":{"type":"boolean","description":"New enabled state. Omit to leave it unchanged."}},"required":["agentId","name"]}}}},"responses":{"200":{"description":"Update a managed MCP server result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}},"delete":{"tags":["Mcp"],"summary":"Remove a managed MCP server","description":"Remove a managed server from an agent. Reversible by adding it again (which re-prompts for approval).","parameters":[{"schema":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"required":true,"description":"The id of the agent whose managed MCP servers this acts on.","name":"agentId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."},"required":true,"description":"The managed server name, unique within the agent.","name":"name","in":"query"}],"responses":{"200":{"description":"Remove a managed MCP server result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}/enable":{"post":{"tags":["Mcp"],"summary":"Enable a managed MCP server","description":"Enable a managed server so its tools are injected on the agent’s next turn — no restart, a server enabled mid-conversation is live on the next message. No new command is introduced (it was approved at add), so no approval is needed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."}},"required":["agentId","name"]}}}},"responses":{"200":{"description":"Enable a managed MCP server result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}/disable":{"post":{"tags":["Mcp"],"summary":"Disable a managed MCP server","description":"Disable a managed server, removing its tools from the next turn’s injection while keeping its already-approved configuration on the manifest.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."}},"required":["agentId","name"]}}}},"responses":{"200":{"description":"Disable a managed MCP server result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedMcpServer"}}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}/test":{"post":{"tags":["Mcp"],"summary":"Test a managed MCP server","description":"Probe whether a managed server is reachable and how many tools it exposes. Safe by construction: it only ever connects to an already-approved entry, so it cannot run an arbitrary command and bypass add’s gate. A failure is reported in-band; an OAuth server that needs sign-in reports needsAuth so the caller can offer mcp.signin.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."}},"required":["agentId","name"]}}}},"responses":{"200":{"description":"Test a managed MCP server result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the server connected and listed its tools."},"toolCount":{"type":"number","description":"How many tools it exposes, when reachable."},"error":{"type":"string","description":"The failure reason, when unreachable."},"needsAuth":{"type":"boolean","description":"True when the probe failed with a 401 and the server needs OAuth sign-in."}},"required":["ok"]}}}}}}},"/api/agents/{agentId}/mcp-servers/{name}/client":{"put":{"tags":["Mcp"],"summary":"Use your own app credentials for a managed MCP server","description":"Store the app credentials a person got from a service that will not let DorkOS register itself, so the next sign-in uses their app. Saving replaces the server’s stored sign-in, so the person signs in again afterwards.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The id of the agent whose managed MCP servers this acts on."},"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The managed server name, unique within the agent."},"clientId":{"type":"string","minLength":1,"description":"The client id (sometimes \"app id\") the provider issued."},"clientSecret":{"type":"string","minLength":1,"description":"The client secret, when the provider issued one."}},"required":["agentId","name","clientId"]}}}},"responses":{"200":{"description":"Use your own app credentials for a managed MCP server result","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean","enum":[true],"description":"The credentials were stored; sign in again to use them."}},"required":["saved"]}}}}}}},"/api/capabilities/catalog":{"get":{"tags":["Capabilities"],"summary":"List capabilities","description":"$113","parameters":[{"schema":{"type":"string","minLength":1,"description":"Return only capabilities in this id domain, e.g. 'mcp' matches every mcp.* id. Case-insensitive, exact domain match."},"required":false,"description":"Return only capabilities in this id domain, e.g. 'mcp' matches every mcp.* id. Case-insensitive, exact domain match.","name":"domain","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Return only capabilities whose id, title, or description contains this text (case-insensitive substring)."},"required":false,"description":"Return only capabilities whose id, title, or description contains this text (case-insensitive substring).","name":"query","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Return only capabilities behind this per-agent grant, e.g. roomsManage — the ones a person has to switch on for an agent before they run at all. Exact match, case-sensitive, and it narrows like the two filters above."},"required":false,"description":"Return only capabilities behind this per-agent grant, e.g. roomsManage — the ones a person has to switch on for an agent before they run at all. Exact match, case-sensitive, and it narrows like the two filters above.","name":"toolGroup","in":"query"},{"schema":{"type":"string","enum":["compact","full"],"description":"'compact' returns id, title, tier, and a one-line summary; 'full' adds the model-facing description and the input and output JSON Schemas. Defaults to compact, and to full only when a domain, query or toolGroup filter narrows the catalog to 8 matches or fewer. A broad filter stays compact — ask for full detail explicitly if you want it."},"required":false,"description":"'compact' returns id, title, tier, and a one-line summary; 'full' adds the model-facing description and the input and output JSON Schemas. Defaults to compact, and to full only when a domain, query or toolGroup filter narrows the catalog to 8 matches or fewer. A broad filter stays compact — ask for full detail explicitly if you want it.","name":"detail","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Maximum entries to return in this page (1 to 200, default 50). When more match, the response carries a nextCursor."},"required":false,"description":"Maximum entries to return in this page (1 to 200, default 50). When more match, the response carries a nextCursor.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque token from a previous response’s nextCursor. Omit for the first page."},"required":false,"description":"Opaque token from a previous response’s nextCursor. Omit for the first page.","name":"cursor","in":"query"}],"responses":{"200":{"description":"List capabilities result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"catalogVersion":{"type":"string"},"generatedAt":{"type":"string"},"total":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"nextCursor":{"type":"string"},"guidance":{"type":"string"},"detail":{"type":"string","enum":["compact"]},"capabilities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"tier":{"type":"string","enum":["observe","act","destructive"]},"summary":{"type":"string"}},"required":["id","title","tier","summary"]}}},"required":["catalogVersion","generatedAt","total","returned","offset","detail","capabilities"]},{"type":"object","properties":{"catalogVersion":{"type":"string"},"generatedAt":{"type":"string"},"total":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"nextCursor":{"type":"string"},"guidance":{"type":"string"},"detail":{"type":"string","enum":["full"]},"capabilities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tier":{"type":"string","enum":["observe","act","destructive"]},"inputSchema":{"type":"object","additionalProperties":{}},"outputSchema":{"type":"object","additionalProperties":{}},"surfaces":{"type":"object","properties":{"mcp":{"type":"object","properties":{"toolName":{"type":"string"},"servers":{"type":"array","items":{"type":"string","enum":["in-session","external"]}},"readOnlyCarveOut":{"type":"boolean"},"annotations":{"type":"object","properties":{"openWorldHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"}}}},"required":["toolName","servers"]},"cli":{"type":"object","properties":{"verb":{"type":"string"},"subcommand":{"type":"string"}},"required":["verb"]},"http":{"type":"object","properties":{"method":{"type":"string","enum":["get","post","put","patch","delete"]},"path":{"type":"string"}},"required":["method","path"]}}},"toolGroup":{"type":"string"}},"required":["id","title","description","tier","inputSchema","outputSchema","surfaces"]}}},"required":["catalogVersion","generatedAt","total","returned","offset","detail","capabilities"]}]}}}}}}}},"webhooks":{}}},"proxyUrl":"$undefined"}}]]}]]}]

Read requester-safe status for one program review

Path Parameters

Response Body

200application/json

404application/json

`application/json`

`application/json`