CodesTask codes.task@1

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

Version
1.0.0
Owner
codes
Visibility
first-party
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/codes/task.v1.json

codes.task@1: a coding task on OpenVibe.Codes, as GET /api/v1/tasks/:id answers it (capability codes.task.read) and POST /api/v1/tasks creates it. STATE follows the OpenVibe.Run job that carries it: queued (waiting for one of the person's machines), placed, running, then succeeded, failed, cancelled or expired (no machine of theirs took it in time). URL is the task's page on openvibe.codes, where its owner follows it live. RESULT is present once it has ended: OK says whether the agents finished, SUMMARY what they said, FILES and PATCH the change (the patch at most 256 KiB, PATCH_TRUNCATED when cut), PUSH where it went when asked, COST_USD the model use on the person's own keys, DURATION_MS the time on their machine. ERROR says why a task that never ran ended (Run refused it, or the job failed before a result).

Fields

FieldTypeRequiredDescriptionConstraints
idstringyesThe Codes task id (tsk_ + ULID).
  • pattern ^tsk_[0-9A-HJKMNP-TV-Z]{26}$
stateenumyes
  • one of "queued", "placed", "running", "succeeded", "failed", "cancelled", "expired"
repostringyes
  • maxLength 300
refstring | null
  • maxLength 200
agentstring | null
  • maxLength 41
urlstringyes
  • pattern ^https://
  • format uri
created_atstringyes
  • format date-time
updated_atstringyes
  • format date-time
errorstring | null
  • maxLength 1000
resultobject
  • no other fields
result.okbooleanyes
result.agentsarray of string
  • maxItems 20
  • items: maxLength 41
result.summarystring
  • maxLength 4000
result.filesarray of object
  • maxItems 2000
  • items: no other fields
result.files[].pathstringyes
  • minLength 1
  • maxLength 500
result.files[].addedinteger | null
  • minimum 0
result.files[].removedinteger | null
  • minimum 0
result.patchstring
  • maxLength 262144
result.patch_truncatedboolean
result.pushobject
  • no other fields
result.push.pushedbooleanyes
result.push.branchstring
  • maxLength 200
result.push.branch_urlstring
  • format uri
result.push.pull_requeststring
  • format uri
result.push.pull_request_errorstring
  • maxLength 500
result.push.reasonstring
  • maxLength 500
result.cost_usdnumber
  • minimum 0
result.duration_msinteger
  • minimum 0
result.errorstring
  • maxLength 1000

Examples

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

Valid: failed-before-running
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "failed",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z",
  "error": "run.job.unplaceable: no machine of yours runs code jobs"
}
Valid: queued
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "queued",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z"
}
Valid: succeeded
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "succeeded",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:01:12.000Z",
  "result": {
    "ok": true,
    "agents": [
      "deepseek"
    ],
    "summary": "Appended the line.",
    "files": [
      {
        "path": "README",
        "added": 1,
        "removed": 0
      }
    ],
    "patch": "diff --git a/README b/README\n--- a/README\n+++ b/README\n@@ -1 +1,2 @@\n Hello World!\n+Edited.\n",
    "cost_usd": 0.0011,
    "duration_ms": 4200,
    "push": {
      "pushed": false,
      "reason": "no GITHUB_TOKEN on this machine"
    }
  }
}
Rejected: bad-id
{
  "id": "task_1",
  "state": "queued",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z"
}
Rejected: http-url
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "queued",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "http://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z"
}
Rejected: result-without-ok
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "succeeded",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z",
  "result": {
    "summary": "x"
  }
}
Rejected: unknown-state
{
  "id": "tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "state": "paused",
  "repo": "https://github.com/octocat/Hello-World",
  "ref": null,
  "agent": "deepseek",
  "url": "https://openvibe.codes/run/tasks/tsk_01M4XEV0JT93CAYTXVD6V0QW1E",
  "created_at": "2026-10-14T15:00:00.000Z",
  "updated_at": "2026-10-14T15:00:00.000Z"
}

Validate

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