Capability YAML

capability.yaml is the agent-side source of truth. It defines what can be called, what input is accepted, what SQL is executed, and which output columns may leave the database boundary.

Structure

service:
  title: Example CRM Capabilities
  version: 0.1.0
  description: Agent-defined capabilities for a legacy CRM database.
 
gateway:
  url: "wss://customer-abc.example.com/ws/agent"
  agent_private_key: "base64url-ed25519-private-key"
 
database:
  driver: postgres
  host: localhost
  port: 5432
  name: legacy_db
  user: readonly_user
  password: ""
 
logging:
  max_size: 10MB
  max_files: 3
 
defaults:
  readonly: true
  timeout: 30s
  max_rows: 1000
  max_bytes: 1MB
 
capabilities:
  get_customers:
    description: "Fetch customers by status"
    sql: |
      SELECT id, name, email FROM customers
      WHERE status = :status LIMIT :limit
    params:
      status:
        type: string
        enum: ["active", "inactive"]
        description: "Customer status"
      limit:
        type: integer
        default: 50
        minimum: 1
        maximum: 500
        description: "Number of rows to return"
    policy:
      readonly: true
      timeout: 5s
      max_rows: 500
      max_bytes: 256KB
      expose_in_openapi: true
    result:
      id:
        type: integer
        description: "Customer ID"
      name:
        type: string
        description: "Customer name"
      email:
        type: string
        description: "Email address"

Top-Level Sections

Supported database drivers are postgres, mysql, sqlserver, and oracle.

Capability names must match ^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$.

Descriptions

description fields are optional but recommended. They are public metadata used to make generated OpenAPI and MCP tools understandable to API users and AI agents.

Descriptions do not grant permissions, change validation, affect SQL execution, or bypass policy / result enforcement. Security behavior is defined by capability names, API key authorization, params validation, policy, SQL, and result allow-lists.

For AI/MCP use, write descriptions as stable business-facing contract text. Do not put secrets, internal-only incident detail, DB credentials, or sensitive operational notes in descriptions because they can appear in OpenAPI and MCP metadata.

Gateway

Database

Current DSN generation adds sslmode=disable for PostgreSQL and encrypt=disable for SQL Server.

Logging

The local detail log path is the agent executable path plus .log, for example onprest-agent.log.

Defaults

defaults is optional. It supplies policy defaults for capabilities, and each capability’s own policy values take precedence.

If neither defaults nor capability policy sets a value, the implementation defaults are:

Capabilities

Each entry under capabilities defines one externally callable operation.

Params

params defines the input contract.

Unknown params are rejected.

minimum and maximum are integer-valued bounds and apply to integer and number params. JSON numbers are accepted for numeric params; integer rejects fractional values.

Policy

policy limits execution.

Use read-only DB users for read capabilities. YAML policy is an application guard; DB privileges should still enforce least privilege.

When readonly is true, startup lint rejects non-read-only SQL. timeout, max_rows, and max_bytes are enforced during capability execution.

Result Allow-List

result is the output allow-list.

• Columns not listed in result are removed from the response.
• If SQL does not return a column listed in result, execution fails.
• If result is omitted, row object fields are not returned.
• Even with SELECT *, only result-listed columns can leave the agent boundary.

This is the final guard that prevents accidental exposure of extra columns.

Supported result column types are string, integer, number, and boolean.