ActorAssignment actor.assignment@1

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

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

actor.assignment@1: one node of the tree of delegated work (plan §12). A node is a hand-off — a person giving Actor a task, a routine or Watch trigger starting a run, an agent handing work to another agent, or Actor starting a Codes or Space task. ID is the node; ROOT names the node whose BUDGET the whole tree spends, PARENT the node that handed this work over (null on a root) and DEPTH its distance from the root (0 on a root). ORIGIN says who started the line: a person (person), a routine or Watch trigger (routine), or work from outside Actor (outside). MODE is the hand-off's kind (work, consult, notify) and REPLY how its result comes back (resume into the parent, poll, or none). LEVEL is the node's own level and EFFECTIVE_LEVEL the level its steps run at: the higher of the agent's own level and the one inherited from a person's or routine's line. Outside work never passes a level down. BUDGET is the root's budget and what the tree has spent. A cancel cascades down the tree. GET /api/v1/assignments/:id returns { assignment, children } and POST /api/v1/assignments/:id/cancel returns { assignment, cancelled }; both are owner-only, and another person's node is the same 404 as one that does not exist. A task has no node until one is made for it: an existing task gets a root lazily.

Fields

FieldTypeRequiredDescriptionConstraints
idstringyes
  • pattern ^asg_[0-9A-HJKMNP-TV-Z]{26}$
rootstringyes
  • pattern ^asg_[0-9A-HJKMNP-TV-Z]{26}$
parentstring | nullyes
  • pattern ^asg_[0-9A-HJKMNP-TV-Z]{26}$
depthintegeryes
  • minimum 0
originenumyes
  • one of "person", "routine", "outside"
modeenumyes
  • one of "work", "consult", "notify"
replyenumyes
  • one of "resume", "poll", "none"
agent_idstring | nullyes
  • pattern ^agt_[0-9A-HJKMNP-TV-Z]{26}$
task_idstring | nullyes
  • pattern ^tsk_[0-9A-HJKMNP-TV-Z]{26}$
levelenumyes
  • one of "ask", "auto-edits", "approve-for-me", "full"
effective_levelenumyes
  • one of "ask", "auto-edits", "approve-for-me", "full"
budgetobjectyesThe budget of the root of this tree, and what the tree has spent of it. Every node carries the same root budget.
  • no other fields
budget.limit_usdnumberyes
  • minimum 0
budget.spent_usdnumberyes
  • minimum 0
budget.remaining_usdnumberyes
  • minimum 0
stateenumyes
  • one of "queued", "running", "waiting", "succeeded", "failed", "cancelled"
created_atstringyes
  • format date-time
updated_atstringyes
  • format date-time
started_atstring | null
  • format date-time
ended_atstring | null
  • format date-time

Examples

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

Valid: child
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPT",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "depth": 1,
  "origin": "routine",
  "mode": "consult",
  "reply": "poll",
  "agent_id": null,
  "task_id": null,
  "level": "auto-edits",
  "effective_level": "auto-edits",
  "budget": {
    "limit_usd": 0.05,
    "spent_usd": 0.0012,
    "remaining_usd": 0.0488
  },
  "state": "queued",
  "created_at": "2026-11-07T10:00:02.000Z",
  "updated_at": "2026-11-07T10:00:02.000Z"
}
Valid: outside-done
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPX",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPX",
  "parent": null,
  "depth": 0,
  "origin": "outside",
  "mode": "notify",
  "reply": "none",
  "agent_id": null,
  "task_id": "tsk_01JAB2C3D4E5F6G7H8J9K0MNPT",
  "level": "full",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 0,
    "spent_usd": 0,
    "remaining_usd": 0
  },
  "state": "succeeded",
  "created_at": "2026-11-07T10:00:03.000Z",
  "updated_at": "2026-11-07T10:00:09.000Z",
  "started_at": "2026-11-07T10:00:03.000Z",
  "ended_at": "2026-11-07T10:00:09.000Z"
}
Valid: root
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": 0,
  "origin": "person",
  "mode": "work",
  "reply": "resume",
  "agent_id": "agt_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "task_id": "tsk_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "level": "ask",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 0.05,
    "spent_usd": 0.0012,
    "remaining_usd": 0.0488
  },
  "state": "running",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:05.000Z",
  "started_at": "2026-11-07T10:00:01.000Z",
  "ended_at": null
}
Rejected: bad-origin
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": 0,
  "origin": "webhook",
  "mode": "work",
  "reply": "resume",
  "agent_id": null,
  "task_id": null,
  "level": "ask",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 1,
    "spent_usd": 0,
    "remaining_usd": 1
  },
  "state": "queued",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:00.000Z"
}
Rejected: bad-state
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": 0,
  "origin": "person",
  "mode": "work",
  "reply": "resume",
  "agent_id": null,
  "task_id": null,
  "level": "ask",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 1,
    "spent_usd": 0,
    "remaining_usd": 1
  },
  "state": "paused",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:00.000Z"
}
Rejected: missing-budget
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": 0,
  "origin": "person",
  "mode": "work",
  "reply": "resume",
  "agent_id": null,
  "task_id": null,
  "level": "ask",
  "effective_level": "ask",
  "state": "queued",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:00.000Z"
}
Rejected: negative-depth
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": -1,
  "origin": "person",
  "mode": "work",
  "reply": "resume",
  "agent_id": null,
  "task_id": null,
  "level": "ask",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 1,
    "spent_usd": 0,
    "remaining_usd": 1
  },
  "state": "queued",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:00.000Z"
}
Rejected: unknown-field
{
  "id": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "root": "asg_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "parent": null,
  "depth": 0,
  "origin": "person",
  "mode": "work",
  "reply": "resume",
  "agent_id": null,
  "task_id": null,
  "level": "ask",
  "effective_level": "ask",
  "budget": {
    "limit_usd": 1,
    "spent_usd": 0,
    "remaining_usd": 1
  },
  "state": "queued",
  "created_at": "2026-11-07T10:00:00.000Z",
  "updated_at": "2026-11-07T10:00:00.000Z",
  "owner": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPS"
}

Validate

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