---
title: "common.action-item@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/common.action-item"
updated: null
---
# common.action-item@1 · OpenVibe.Services
HTML: [common.action-item@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/common.action-item)
# ActionItem `common.action-item@1`
Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/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`](/docs/contracts/common.action-item.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
| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `service` | enum | yes | The authority that owns the item. | - `one of "actor", "codes", "ai", "network", "run", "domains"` |
| `id` | string | yes | The authority's own id (tsk\_…, a Codes task id, run\_…, a confirmation id, dpr\_…). | - `minLength 1`
- `maxLength 80` |
| `kind` | enum | yes | What the item is. | - `one of "agent_task", "code_task", "ai_run", "approval", "desk_session"` |
| `title` | string | yes | A short plain-text name: the start of the task text, the workflow, or what the approval is for. | - `minLength 1`
- `maxLength 160` |
| `summary` | string \| null | | The last step, the outcome, or what will happen on approval. | - `maxLength 400` |
| `bucket` | enum | yes | Where 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"` |
| `state` | string | yes | The authority's own state word (queued, running, needs\_you, succeeded, failed, cancelled, pending…). | - `minLength 1`
- `maxLength 32` |
| `agent` | string \| null | | The agent, model or workflow doing it, when known. | - `maxLength 80` |
| `cost_usd` | number \| null | | What it cost the person, in US dollars; null when unknown or free. | - `minimum 0` |
| `steps` | integer \| null | | Tool calls or steps so far, when counted. | - `minimum 0` |
| `error` | string \| null | | Why it failed, in words a person can act on. | - `maxLength 400` |
| `created_at` | string | yes | | - `format date-time` |
| `updated_at` | string | yes | | - `format date-time` |
| `next_run_at` | string \| null | | When a scheduled item runs next. | - `format date-time` |
| `href` | string | yes | The item's page: its live steps, receipt or approval. | - `pattern ^https://`
- `format uri`
- `maxLength 2048` |
| `actions` | array of enum | yes | What 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"` |
| `skill` | string \| null | | Catalogue skill key, when this run came from a skill. | - `maxLength 120` |
| `subject` | object \| null | | The content this run is about, with its canonical page when known. | |
| `model` | string \| null | | | - `maxLength 120` |
| `maker` | string \| null | | | - `maxLength 80` |
| `duration_ms` | integer \| null | | | - `minimum 0` |
| `run_error` | one of | | Safe error words and the next useful action. Never a raw provider response. | |
| `step` | string \| null | | The 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 }] }
~~~~