From cc0bf3467b33c32922ec78eb0cf4fffbd90483c2 Mon Sep 17 00:00:00 2001 From: Anders Betts Date: Sun, 20 Sep 2026 09:35:06 +0200 Subject: commands: declarative argument schemas with dispatch validation --- docs/PROTOCOL.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index 16fd2c5..00f5200 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -220,20 +220,33 @@ The discovery commands themselves: ### 6.2 `describe` Returns the full command catalogue. `describe {"cmd":"voucher.post"}` returns -one entry. Each entry: +one entry. Each entry carries a declarative argument schema: ```json { "name":"voucher.post","summary":"Post an immutable voucher", "permission":{"role":"bookkeeper","require_org":true}, "mutating":true,"dry_run":true, - "args":{"date":{"type":"date","required":true}, - "rows":{"type":"array","min":2,"of":{...}}}, - "result":{...}, - "examples":[{"args":{...},"result":{...}}] + "args":[ + {"name":"date","type":"date","required":true, + "description":"Voucher date (YYYY-MM-DD)"}, + {"name":"description","type":"string","required":false}, + {"name":"rows","type":"json","required":false, + "description":"Array of {account,debit_ore,credit_ore,description?}"} + ] } ``` +`args` is an array in validation order. `type` is one of `string`, `int`, +`bool`, `enum`, `date` or `json`; `required` tells whether the argument must +be present (and, for `string`/`enum`, non-empty); `default` gives the +documented default; `values` lists the allowed values of an `enum`; and +`description` is a one-line summary. `json` covers structured values (rows, +entries, ids, selections). The daemon validates every present argument +against this schema before the handler runs and answers `INVALID_ARGS` for a +missing required argument or a wrong type; unknown arguments are ignored for +forward compatibility. Commands without arguments emit an empty array. + This is the primary integration surface for agents: call `describe`, then act. ### 6.3 `agent.instructions` -- cgit v1.3