Agent Overview

onprest-agent runs next to the database. It owns the meaning of every capability and is the only OSS core component that holds DB connection details and SQL.

Runtime Model

• Single Go binary.
• Configured by capability.yaml.
• Connects outbound to gateway over WebSocket.
• Does not open an inbound HTTP server.
• Reconnects every 30 seconds by default when gateway is unavailable.
• Requires restart to pick up capability changes.

Startup Checks

Before connecting to gateway, agent performs:

1. capability.yaml load.
2. Structural lint and required-field validation.
3. DB ping.
4. SQL EXPLAIN verification for each capability.

If DB ping or EXPLAIN fails, startup is aborted. Detail is written to onprest-agent.log; stderr stays generic so SQL and DB-specific detail are not exposed to process supervisors or remote logs.

Execution Flow

When gateway sends a capability request, agent:

1. Rejects unknown capability names.
2. Validates params against the YAML contract.
3. Applies policy settings.
4. Executes SQL with prepared parameters.
5. Applies the result allow-list.
6. Returns either result or a normalized agent error code.

Error detail remains local to the agent side.