rungent v0.5.1
EN中文

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-rungent object has an unknown key, a missing name, or a value of the wrong type or length;
  • two operations have the same name;
  • there is not exactly one role: identity operation;
  • a GET or HEAD operation, or a role operation, has an effect other than read;
  • 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 $ref points outside #/components/schemas or at nothing;
  • one input name appears twice (a path parameter and a body field, say);
  • form names an operation that is not role: form;
  • a resolve key is not an input, or its op is not a read operation without a role;
  • next.op is not a catalog operation, or is a role operation;
  • a cli.args entry is not an input;
  • a confirmation placeholder other than {resource_name} is not an input;
  • a confirmation has a lookup but no {resource_name} in its title;
  • lookup.path is not served by a GET operation of the catalog;
  • open or lookup.path does not start with a single /.

The input schema each operation gets is on The catalog.

For agents: x-rungent.mdEdit this page