rungentReference
x-rungent
Every key of the x-rungent OpenAPI extension, its type, its default and what it does, with the rules a catalog must pass.
An operation of your OpenAPI 3.1 document joins the catalog when it carries an x-rungent object.
Operations without one are invisible to rungent, and an unknown key inside one fails validation.
What the keys mean together is on The catalog.
"post": {
"summary": "Stop server",
"x-rungent": {
"name": "stop_vm",
"description": "Stop a running cloud server (VM).",
"effect": "update",
"resolve": { "vm_id": { "op": "list_vms" } },
"open": "/console/instance/{vm_id}",
"confirmation": {
"title": "Stop server {resource_name}?",
"lookup": { "path": "/api/vms/{vm_id}", "labelPath": "name" },
"risk": "medium"
},
"cli": { "command": "vm stop", "args": ["vm_id"] }
}
}
Every key#
| Key | Type | Default | Meaning |
|---|---|---|---|
name |
^[a-z][a-z0-9_]{0,63}$ |
required | The stable name, unique in the catalog: the tool name for the model and MCP, the CLI command with _ as -, the assertion's op. |
title |
string, 1–80 | the OpenAPI summary, else name |
The label people see: approval cards, activity rows, CLI help. |
description |
string, 1–500 | the OpenAPI summary, else title |
What the model reads to choose the operation. Name the resource and its synonyms ("cloud server (VM)"). |
effect |
read create update delete external |
read for role operations; else from the method: GET/HEAD read, POST create, PUT/PATCH update, DELETE delete |
What the call does. external reaches outside the product (mail, payment). GET and HEAD must stay read. |
approval |
never always |
never for read, always otherwise |
Whether the user approves each call. See Forms and approvals. |
role |
identity search form |
none | Makes it a special operation; see Roles. |
surfaces |
array of agent mcp cli |
read: all three; writes: agent, cli; role operations: none |
Where it appears. The CLI also sees mcp operations. A write on mcp runs only for clients that can confirm it. |
confirmation |
object | a card from title and the arguments |
The approval card; see Confirmation. |
form |
operation name | none | A role: form operation that supplies this operation's form; its inputs then come only from that form. |
resolve |
{argument: {op, key?}} |
none | Lets the user name a thing instead of giving its id: op is a read operation that lists candidates, key the id field (default id). See Turn names into ids. |
next |
object | none | A follow-up call after success, before the model speaks; see Chains. |
open |
path template starting with one / |
none | The page to show after success, filled from the arguments and the result. Sent as the rungent.ui.open event. |
redact |
array of field names | [] |
Fields removed, at any depth, from results and arguments before the model or an MCP client sees them. Secret-like keys (password, token, api_key, authorization, cookie, …) are always removed. |
repeatable |
boolean | false |
Allows identical successful writes in one run. With false, a second identical write is answered from the first result (deduplicated: true). |
timeoutSeconds |
number, > 0 and ≤ 3600 | 120; 2 for role: search |
How long rungent waits for your API. A search operation may ask for at most 10. |
cli |
{command, args?} |
name with -, no positional arguments |
The CLI spelling: command is lowercase words separated by spaces (vm stop), args the inputs taken as positional arguments, in order. |
Confirmation#
| Key | Type | Meaning |
|---|---|---|
title |
string, 1–200, required | The card's heading. |
target |
string, 1–200 | The thing acted on, shown prominently. Default: the looked-up name. |
fields |
[{key, label, values?}] |
Arguments listed on the card as label: value; values maps raw values to words. |
lookup |
{path, labelPath} |
A GET made as the user before the card; labelPath (a dotted path) of its answer becomes {resource_name}. |
risk |
low medium high |
Shown on the card. |
costHint |
string, 1–200 | One line about cost. |
title, target and lookup.path are templates: {argument} takes an input's value, and
{resource_name} the name the lookup found. lookup.path must be served by a GET operation of
the catalog; if the lookup fails, the call stops before the card.
Chains#
"next": { "op": "commit_vm_draft", "arguments": { "draft_id": "id", "revision": "revision" }, "when": { "status": "prepared" } }
| Key | Type | Meaning |
|---|---|---|
op |
operation name, required | The operation to call next; not a role operation. |
arguments |
{argument: path} |
Each argument of the next call, from a dotted path of this call's result. A missing value stops the chain. |
argumentsFrom |
path | A result path whose object becomes the next call's whole input. arguments may add to it, never overwrite it. |
when |
{path: value} |
Every path of the result must equal its value, or the chain stops. |
The next call goes through its own resolve, confirmation and approval.
Roles#
| Role | Shape it must have | What rungent uses it for |
|---|---|---|
identity |
GET, no inputs. Exactly one per catalog. |
Learns who a credential belongs to: {subject, tenant?, name?, locale?, scopes?}. See Acting as the user. |
search |
GET, a required q query parameter, an optional limit, timeoutSeconds ≤ 10. |
One source of ⌘K, the search tool and MCP search: {hits: [...]}. See Search and knowledge. |
form |
POST, approval: never. |
Answers the generic form for an operation's arguments: {prompt, questions}. See Forms and approvals. |
Role operations are reads, have no surfaces, and are never offered to the model.
Validation rules#
rungent check reports every problem at once, by METHOD /path or operation name. A catalog fails
when:
- the document is not OpenAPI 3.1;
- an
x-rungentobject has an unknown key, a missingname, or a value of the wrong type or length; - two operations have the same
name; - there is not exactly one
role: identityoperation; - a
GETorHEADoperation, or a role operation, has an effect other thanread; - a role operation lists surfaces, or does not have its role's shape above;
- the request body is not
application/json, a header or cookie parameter is required, or a$refpoints outside#/components/schemasor at nothing; - one input name appears twice (a path parameter and a body field, say);
formnames an operation that is notrole: form;- a
resolvekey is not an input, or itsopis not a read operation without a role; next.opis not a catalog operation, or is a role operation;- a
cli.argsentry is not an input; - a confirmation placeholder other than
{resource_name}is not an input; - a confirmation has a
lookupbut no{resource_name}in itstitle; lookup.pathis not served by aGEToperation of the catalog;openorlookup.pathdoes not start with a single/.
The input schema each operation gets is on The catalog.
For agents: x-rungent.mdEdit this page