AgentsApproval agents.approval@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
actor
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-044
Schema
https://openvibe.network/contracts/agents/approval.v1.json

agents.approval@1 (one agent system, 2026-11-12): a run stopped at a step to ask its person before it acts. WHAT is the act in plain words; OPTIONS are the answers the product offers, each with an id and the words a person reads; DECIDED_BY and DECIDED_AT are absent (or null) while it waits; ANSWER is the chosen option's id (or the person's own words, when the product allows them). Nothing the approval covers runs before the answer, and an answer decided once is never decided again. The approval is attached to the run's step (STEP_SEQ), so a step log and an approval list line up. OpenVibe.Actor's approval inbox and OpenVibe.Codes' tool approvals are the same shape; the product keeps the grant.

Fields

FieldTypeRequiredDescriptionConstraints
idstringThe product's own approval id (apr_…), when it has one; STEP_SEQ is still the link to the run.
  • minLength 1
  • maxLength 160
run_idstringyes
  • minLength 1
  • maxLength 160
step_seqintegeryesThe seq of the run's step that asked (agents.step@1's seq).
  • minimum 1
whatstringyesThe act in plain words, with its exact target: "post this to your feed", "run rm -rf build on your machine". Never a raw tool payload.
  • minLength 1
  • maxLength 2000
optionsarray of objectyesThe answers the product offers, in the order to show them. The floor categories (money, a password, a deletion, a new recipient) are asked every time and have no standing permission.
  • minItems 1
  • maxItems 8
  • items: no other fields
options[].idstringyes
  • minLength 1
  • maxLength 80
options[].labelstringyes
  • minLength 1
  • maxLength 80
decided_byone ofWho answered: a person subject, a service or an agent.
decided_atstring | null
  • format date-time
answerstring | nullThe chosen option's id, or the person's own words when the product allows them. Null while it waits.
  • maxLength 2000

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: approved
{
  "id": "apr_01K9R2V6M8Q4T0B7C3D5E9F2GH",
  "run_id": "tsk_01K9R2V6M8Q4T0B7C3D5E9F2GH",
  "step_seq": 7,
  "what": "Push the branch and open a pull request on your machine's repository",
  "options": [
    {
      "id": "approve",
      "label": "Approve"
    },
    {
      "id": "decline",
      "label": "Decline"
    }
  ],
  "decided_by": {
    "type": "user",
    "id": "usr_01K9R2V6M8Q4T0B7C3D5E9F2GH"
  },
  "decided_at": "2026-11-12T10:01:00Z",
  "answer": "approve"
}
Rejected: no-options
{
  "run_id": "tsk_01K9R2V6M8Q4T0B7C3D5E9F2GH",
  "step_seq": 7,
  "what": "Post the answer to your feed",
  "options": []
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('agents.approval@1', value);   // { valid, errors: [{ path, message }] }