Skip to content

x-aidy

A host publishes an OpenAPI 3.1 document. An operation joins the aidy catalog when it carries an x-aidy object; operations without one are invisible to aidy. Unknown keys are rejected. For the ideas behind the catalog, see Catalog and Operations.

"post": {
"operationId": "stopVm",
"x-aidy": {
"name": "stop_vm",
"title": "Stop server",
"description": "Stop a running cloud server (VM).",
"open": "/console/instance/{vm_id}",
"confirmation": {
"title": "Stop server {resource_name}?",
"lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" }
}
}
}

This table is generated at build time from spec/schemas/x-aidy.schema.json, so it always matches the contract.

FieldTypeConstraintRequired
namestringpattern ^[a-z][a-z0-9_]{0,63}$yes
titlestring≤ 80 chars
descriptionstring≤ 500 chars
effect"read" | "create" | "update" | "delete" | "external"
approval"never" | "always"
role"identity" | "search" | "form"
surfaces"agent" | "mcp" | "cli"[]
confirmationobject
confirmation.titlestring≤ 200 charsyes
confirmation.targetstring≤ 200 chars
confirmation.fieldsobject[]
confirmation.fields[].keystringyes
confirmation.fields[].labelstringyes
confirmation.fields[].valuesmap<string, string>
confirmation.lookupobject
confirmation.lookup.pathstringpattern ^\/(?!\/)yes
confirmation.lookup.labelPathstringyes
confirmation.risk"low" | "medium" | "high"
confirmation.costHintstring≤ 200 chars
formstringpattern ^[a-z][a-z0-9_]{0,63}$
resolvemap<string, object>
resolve.<name>.opstringpattern ^[a-z][a-z0-9_]{0,63}$yes
resolve.<name>.keystring
nextobject
next.opstringpattern ^[a-z][a-z0-9_]{0,63}$yes
next.argumentsmap<string, string>
next.argumentsFromstring
next.whenmap<string, any>
openstringpattern ^\/(?!\/)
redactstring[]
repeatableboolean
timeoutSecondsnumber> 0, ≤ 3600
cliobject
cli.commandstringpattern ^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$yes
cli.argsstring[]

Generated from spec/schemas/x-aidy.schema.json at build time; any other key is rejected.

Key Type Meaning
name ^[a-z][a-z0-9_]{0,63}$ Required. Stable tool name, unique in the catalog. Also the MCP tool name and the CLI command (stop_vm → stop-vm).
title string ≤ 80 Human label for approval cards, activity rows and CLI help. Defaults to the OpenAPI summary, then name.
description string ≤ 500 Model-facing description. Name the resource and its common synonyms. Defaults to the OpenAPI summary.
effect read create update delete external What the call does. Defaults from the method: GET/HEAD read, POST create, PUT/PATCH update, DELETE delete. external means it reaches outside the product (mail, payment).
approval never always Whether the user confirms each call. Defaults to never for read and always otherwise.
role identity search form A special operation, see Roles.
surfaces array of agent mcp cli Where the operation appears. Defaults: read → all three; other effects → agent, cli. Listing mcp for a write exposes it only to MCP clients that support confirmation. Role operations have no surfaces.
confirmation object The approval card, see Confirmation.
form operation name A role: form operation that supplies the input form before approval or execution.
resolve {argument: {op, key?}} Name-or-id lookup: before approval, a string argument that is not the key (default id) of an item listed by op is matched against item names. One match replaces it; none or several fail the call with unresolved_reference.
next object A follow-up call run after success before the model speaks, see Chains.
open path template Product page shown after success, filled from arguments and the result ({vm_id}). Must start with /.
redact array of field names Result fields removed before the model or MCP client sees them (for example ip).
repeatable boolean Allows identical successful writes within one run. Default false: an identical write is answered from the first result.
timeoutSeconds number ≤ 3600 Call timeout. Default 120; for a role: search operation default 2 and at most 10 (a larger value is a catalog error).
cli {command, args?} CLI spelling: command is space-separated words (vm stop), args the positional arguments in order. Default: name with - and no positionals.
{
"title": "Stop server {resource_name}?",
"target": "{resource_name}",
"fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }],
"lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" },
"risk": "medium",
"costHint": "Billing continues for disks."
}

Templates take {argument} placeholders and {resource_name}. With lookup, aidy performs an authenticated GET (as the user) before showing approval and reads labelPath from the response as {resource_name}. The lookup path must be served by a GET operation in the catalog, because every call aidy makes names the operation it calls (delegation). A failed lookup aborts the call before approval; nothing runs.

Key Constraint Meaning
title required, ≤ 200 Card heading.
target ≤ 200 The thing acted on, shown prominently.
fields [{key, label, values?}] Arguments shown on the card; values maps raw values to labels.
lookup {path, labelPath} Authenticated GET that supplies {resource_name}.
risk low medium high Shown on the card.
costHint ≤ 200 A line about cost.

See Approvals.

"next": {
"op": "commit_vm_draft",
"arguments": { "draft_id": "id", "revision": "revision" },
"when": { "status": "prepared" }
}

arguments maps the next call’s arguments to paths in this call’s result. argumentsFrom names a result path whose object becomes the whole input (prepared configurations); arguments may then add path parameters but never overwrite it. when must match the result or the chain stops. The next operation’s own approval still applies. See Chains.

Role Shape Use
identity GET, no parameters, read. Exactly one per catalog. Answers the Identity of the credential it is called with.
search GET, a required q query parameter, optional limit, read, timeoutSeconds ≤ 10. One search source, see Search.
form POST, read, approval: never. Receives the target call’s arguments and answers a Form. Never offered to the model.
{
"subject": "u_123",
"tenant": "t_9",
"name": "Ada Lovelace",
"locale": "zh-CN",
"scopes": ["aidy:admin"]
}

subject is required; the rest is optional. aidy:admin lets the user change aidy settings (the model chain). Sessions belong to (subject, tenant). See Identity.

aidy normalizes each annotated operation into one input schema, which the model, MCP, and CLI all see:

  • Path and query parameters become top-level properties.
  • An object request body is flattened into top-level properties. Any other body becomes one body property.
  • A name that appears twice (a path parameter and a body field, say) is a catalog error.
  • $refs into #/components/schemas are kept as $defs references, so recursive schemas remain valid.

The catalog fails validation when:

  • a name is duplicated;
  • a form, resolve, or next reference names no operation, or names one of the wrong role or effect;
  • a role operation has the wrong method or shape;
  • a confirmation lookup.path is not served by a GET operation;
  • open or lookup.path does not start with a single /.

Run aidy check --openapi openapi.json to list every issue; see the CLI reference.