ActionItem common.action-item@1

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

Version
1.1.0
Owner
contracts
Visibility
public
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/common/action-item.v1.json

One piece of a person's agent work in the Action Center (plan 2026-10-28 §3.10): an agent task, a coding task, an AI run, or an approval waiting on them. Each authority answers its own items in this shape (common.action-list-result@1); OpenVibe.Network merges them into buckets (network.me-actions-result@1). Text is plain (no markup); a cost is what the person was charged in USD, null when unknown or free; href is a page on the authority's own public site.

Fields

FieldTypeRequiredDescriptionConstraints
serviceenumyesThe authority that owns the item.
  • one of "actor", "codes", "ai", "network", "run", "domains"
idstringyesThe authority's own id (tsk_…, a Codes task id, run_…, a confirmation id, dpr_…).
  • minLength 1
  • maxLength 80
kindenumyesWhat the item is.
  • one of "agent_task", "code_task", "ai_run", "approval", "desk_session"
titlestringyesA short plain-text name: the start of the task text, the workflow, or what the approval is for.
  • minLength 1
  • maxLength 160
summarystring | nullThe last step, the outcome, or what will happen on approval.
  • maxLength 400
bucketenumyesWhere the Action Center shows it: running (queued or working), waiting (needs the person), scheduled (will run later), done, failed (failed, cancelled or expired).
  • one of "running", "waiting", "scheduled", "done", "failed"
statestringyesThe authority's own state word (queued, running, needs_you, succeeded, failed, cancelled, pending…).
  • minLength 1
  • maxLength 32
agentstring | nullThe agent, model or workflow doing it, when known.
  • maxLength 80
cost_usdnumber | nullWhat it cost the person, in US dollars; null when unknown or free.
  • minimum 0
stepsinteger | nullTool calls or steps so far, when counted.
  • minimum 0
errorstring | nullWhy it failed, in words a person can act on.
  • maxLength 400
created_atstringyes
  • format date-time
updated_atstringyes
  • format date-time
next_run_atstring | nullWhen a scheduled item runs next.
  • format date-time
hrefstringyesThe item's page: its live steps, receipt or approval.
  • pattern ^https://
  • format uri
  • maxLength 2048
actionsarray of enumyesWhat the person can do from the list. approve/decline/cancel/retry go through OpenVibe.Network (POST /api/v1/me/actions/:service/:id/:action); open is a link.
  • maxItems 4
  • items: one of "open", "approve", "decline", "cancel", "retry"
skillstring | nullCatalogue skill key, when this run came from a skill.
  • maxLength 120
subjectobject | nullThe content this run is about, with its canonical page when known.
modelstring | null
  • maxLength 120
makerstring | null
  • maxLength 80
duration_msinteger | null
  • minimum 0
run_errorone ofSafe error words and the next useful action. Never a raw provider response.
stepstring | nullThe latest live step in plain words.
  • maxLength 240

Examples

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

Valid: approval
{
  "service": "network",
  "id": "cnf_01JAB2C3D4E5F6G7H8J9K0MNPR",
  "kind": "approval",
  "title": "Send an email to the venue",
  "summary": "Your agent asks to send one email from your account",
  "bucket": "waiting",
  "state": "pending",
  "created_at": "2026-10-28T14:00:00Z",
  "updated_at": "2026-10-28T14:00:00Z",
  "href": "https://openvibe.network/my#approvals",
  "actions": [
    "approve",
    "decline",
    "open"
  ]
}
Valid: running-task
{
  "service": "actor",
  "id": "tsk_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "kind": "agent_task",
  "title": "Find three cheap flights to Lisbon",
  "summary": "Read 4 pages; comparing prices",
  "bucket": "running",
  "state": "running",
  "agent": "deepseek-flash",
  "cost_usd": 0.004,
  "steps": 6,
  "error": null,
  "created_at": "2026-10-28T14:00:00Z",
  "updated_at": "2026-10-28T14:02:10Z",
  "next_run_at": null,
  "href": "https://openvibe.actor/tasks/tsk_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "actions": [
    "open",
    "cancel"
  ]
}
Rejected: http-href
{
  "service": "actor",
  "id": "tsk_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "kind": "agent_task",
  "title": "Find three cheap flights to Lisbon",
  "summary": "Read 4 pages; comparing prices",
  "bucket": "running",
  "state": "running",
  "agent": "deepseek-flash",
  "cost_usd": 0.004,
  "steps": 6,
  "error": null,
  "created_at": "2026-10-28T14:00:00Z",
  "updated_at": "2026-10-28T14:02:10Z",
  "next_run_at": null,
  "href": "http://openvibe.actor/tasks/x",
  "actions": [
    "open",
    "cancel"
  ]
}
Rejected: unknown-bucket
{
  "service": "actor",
  "id": "tsk_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "kind": "agent_task",
  "title": "Find three cheap flights to Lisbon",
  "summary": "Read 4 pages; comparing prices",
  "bucket": "paused",
  "state": "running",
  "agent": "deepseek-flash",
  "cost_usd": 0.004,
  "steps": 6,
  "error": null,
  "created_at": "2026-10-28T14:00:00Z",
  "updated_at": "2026-10-28T14:02:10Z",
  "next_run_at": null,
  "href": "https://openvibe.actor/tasks/tsk_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "actions": [
    "open",
    "cancel"
  ]
}

Validate

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