AgentsJob agents.job@1

Generated at from openvibe-contracts v0.443.0 and openvibe-sdk v0.177.0.

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

agents.job@1 (one-system-v2.md §7): one job placed on a machine: a check (a repository's tests or one workflow job), a review (an agent of another family reads a diff), a build, an eval, an improvement candidate, a desk or a model. NEEDS is what the place must have; TRUST is public (public code only, no secret ever reaches the place, so community nodes may take it) or owner (only the owner's own machines). PLACEMENT is the scheduler's: cheapest that can, least busy, most reliable; a job that fails because its place went away is tried on another (ATTEMPTS). RESULT carries a named exit, the duration and a link to the masked log. Secrets never travel in a job: a place gets a short-lived token scoped to that one job.

Fields

FieldTypeRequiredDescriptionConstraints
idstringyes
  • pattern ^job_[0-9A-HJKMNP-TV-Z]{26}$
kindenumyes
  • one of "check", "review", "build", "eval", "improve", "desk", "model"
titlestring
  • minLength 1
  • maxLength 160
statusenumyes
  • one of "queued", "placed", "running", "passed", "failed", "cancelled", "expired"
trustenumyes
  • one of "public", "owner"
repoobject
  • no other fields
repo.urlstringyes
  • pattern ^https://
  • maxLength 500
repo.refstring
  • minLength 1
  • maxLength 200
repo.shastringyes
  • pattern ^[0-9a-f]{40}$
runobjectWhat to run: one command, or one job of a workflow file (act's semantics: stages of steps, outputs through files).
  • no other fields
run.commandstring
  • minLength 1
  • maxLength 2000
run.workflowstring
  • minLength 1
  • maxLength 300
run.jobstring
  • minLength 1
  • maxLength 100
run.matrixobject
needsobject
  • no other fields
needs.osenum
  • one of "linux", "macos", "windows", "android"
needs.cpusinteger
  • minimum 1
  • maximum 256
needs.memory_mbinteger
  • minimum 64
  • maximum 2097152
needs.gpuboolean
needs.nodestring
  • minLength 1
  • maxLength 20
needs.browserboolean
needs.toolsarray of string
  • maxItems 20
  • unique items
  • items: pattern ^[a-z][a-z0-9-]{0,40}$
budgetobject
  • no other fields
budget.secondsinteger
  • minimum 1
  • maximum 86400
budget.usdnumber
  • minimum 0
  • maximum 100000
placementobject | null
attemptsinteger
  • minimum 0
  • maximum 20
resultobject | null
parent_runstringThe run that asked for it (agents.run@1 ref), when one did.
  • minLength 1
  • maxLength 200
created_atstringyes
  • format date-time
updated_atstring
  • format date-time

Examples

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

Valid: a-check-on-a-shared-node
{
  "id": "job_01JD8C4QJ7Z3K9W2X5V6N1M0PA",
  "kind": "check",
  "title": "OpenVibe.Shared #513: test",
  "status": "passed",
  "trust": "public",
  "repo": {
    "url": "https://github.com/OpenVibers/OpenVibe.Shared",
    "ref": "own-icon-markup-1112",
    "sha": "768ed2a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6"
  },
  "run": {
    "workflow": ".github/workflows/ci.yml",
    "job": "test"
  },
  "needs": {
    "os": "linux",
    "cpus": 2,
    "memory_mb": 4096,
    "node": "22"
  },
  "budget": {
    "seconds": 1800
  },
  "placement": {
    "node": "lnk_01M78BBHN4QDE4NP06T8J5N0NR",
    "name": "ov-node-01",
    "why": "free, idle, 100% of its last 20 checks finished",
    "placed_at": "2026-11-12T23:00:00Z"
  },
  "attempts": 1,
  "result": {
    "exit": "passed",
    "summary": "41/41 test files passed",
    "duration_ms": 412000
  },
  "created_at": "2026-11-12T23:00:00Z",
  "updated_at": "2026-11-12T23:00:00Z"
}
Valid: a-review-queued
{
  "id": "job_01JD8C4QJ7Z3K9W2X5V6N1M0PB",
  "kind": "review",
  "status": "queued",
  "trust": "public",
  "repo": {
    "url": "https://github.com/OpenVibers/OpenVibe.Live",
    "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "placement": null,
  "created_at": "2026-11-12T23:00:00Z"
}
Rejected: a-secret-in-the-run
{
  "id": "job_01JD8C4QJ7Z3K9W2X5V6N1M0PC",
  "kind": "check",
  "status": "queued",
  "trust": "public",
  "run": {
    "command": "npm test",
    "env": {
      "TOKEN": "x"
    }
  },
  "created_at": "2026-11-12T23:00:00Z"
}
Rejected: a-trust-nobody-has
{
  "id": "job_01JD8C4QJ7Z3K9W2X5V6N1M0PD",
  "kind": "check",
  "status": "queued",
  "trust": "anyone",
  "created_at": "2026-11-12T23:00:00Z"
}

Validate

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