---
title: "agents.job@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/agents.job"
updated: null
---

# agents.job@1 · OpenVibe.Services

HTML: [agents.job@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/agents.job)

# AgentsJob `agents.job@1`

Generated at 2026-11-17 06:52:56 UTC from [`openvibe-contracts v0.443.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.443.0) and [`openvibe-sdk v0.177.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.177.0).

- Version: 1.0.0
- Owner: actor
- Visibility: public
- Status: active
- Compatibility: backward
- Decision: [ADR-044](/docs/adr/ADR-044)
- Schema: [`https://openvibe.network/contracts/agents/job.v1.json`](/docs/contracts/agents.job.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

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | - `pattern ^job_[0-9A-HJKMNP-TV-Z]{26}$` |
| `kind` | enum | yes |  | - `one of "check", "review", "build", "eval", "improve", "desk", "model"` |
| `title` | string |  |  | - `minLength 1`<br>- `maxLength 160` |
| `status` | enum | yes |  | - `one of "queued", "placed", "running", "passed", "failed", "cancelled", "expired"` |
| `trust` | enum | yes |  | - `one of "public", "owner"` |
| `repo` | object |  |  | - `no other fields` |
| `repo.url` | string | yes |  | - `pattern ^https://`<br>- `maxLength 500` |
| `repo.ref` | string |  |  | - `minLength 1`<br>- `maxLength 200` |
| `repo.sha` | string | yes |  | - `pattern ^[0-9a-f]{40}$` |
| `run` | object |  | What to run: one command, or one job of a workflow file (act's semantics: stages of steps, outputs through files). | - `no other fields` |
| `run.command` | string |  |  | - `minLength 1`<br>- `maxLength 2000` |
| `run.workflow` | string |  |  | - `minLength 1`<br>- `maxLength 300` |
| `run.job` | string |  |  | - `minLength 1`<br>- `maxLength 100` |
| `run.matrix` | object |  |  |  |
| `needs` | object |  |  | - `no other fields` |
| `needs.os` | enum |  |  | - `one of "linux", "macos", "windows", "android"` |
| `needs.cpus` | integer |  |  | - `minimum 1`<br>- `maximum 256` |
| `needs.memory_mb` | integer |  |  | - `minimum 64`<br>- `maximum 2097152` |
| `needs.gpu` | boolean |  |  |  |
| `needs.node` | string |  |  | - `minLength 1`<br>- `maxLength 20` |
| `needs.browser` | boolean |  |  |  |
| `needs.tools` | array of string |  |  | - `maxItems 20`<br>- `unique items`<br>- `items: pattern ^[a-z][a-z0-9-]{0,40}$` |
| `budget` | object |  |  | - `no other fields` |
| `budget.seconds` | integer |  |  | - `minimum 1`<br>- `maximum 86400` |
| `budget.usd` | number |  |  | - `minimum 0`<br>- `maximum 100000` |
| `placement` | object \| null |  |  |  |
| `attempts` | integer |  |  | - `minimum 0`<br>- `maximum 20` |
| `result` | object \| null |  |  |  |
| `parent_run` | string |  | The run that asked for it (agents.run@1 ref), when one did. | - `minLength 1`<br>- `maxLength 200` |
| `created_at` | string | yes |  | - `format date-time` |
| `updated_at` | string |  |  | - `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 }] }
~~~~
