# 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](catalog.md).

```json
"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](forms-and-approvals.md). |
| `role` | `identity` `search` `form` | none | Makes it a special operation; see [Roles](#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](#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](catalog.md#turn-names-into-ids). |
| `next` | object | none | A follow-up call after success, before the model speaks; see [Chains](#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

```json
"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](acting-as-the-user.md#who-the-user-is). |
| `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](search.md#add-a-search-source). |
| `form` | `POST`, `approval: never`. | Answers the generic form for an operation's arguments: `{prompt, questions}`. See [Forms and approvals](forms-and-approvals.md#declare-the-form). |

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](catalog.md#the-input-schema).
