ActorTrigger actor.trigger@1

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

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

actor.trigger@1: a trigger made in an Actor conversation — something that runs on a schedule, when a Watch event arrives, or (kind goal) keeps working toward a goal. ID is the trigger, OWNER the person it belongs to, AGENT_ID the agent it runs as, TASK what it runs, and KIND schedule (WHEN has a five-field CRON in the person's TIMEZONE), event (WHEN has the Watch event PATTERN and FILTER), goal (checked on WHEN's CRON, with GOAL saying what it works toward) or mention (waits for the person to say one of WHEN.MENTION's phrases in their own conversation with their own agent). WHEN.WORDS is always the plain-language line shown on the card. NEXT_RUN_AT is the next scheduled occurrence (null for an event trigger), LAST_RUN is the newest run of the trigger with its result (ok, failed, needs_you or running) and WHEN_AT, STATE is active, paused or done (a goal ended itself when its done-test passed), PAUSED_REASON says why (person, failed after five failed runs in a row, or for a goal: done, budget or deadline), and FAILURES is the consecutive failed-run count. WATCH is the subscription's own state when it is an event trigger (a schedule trigger has its Watch schedule too), null when Watch is not reachable. GOAL is present only for a goal: the goal in words, the done-test the agent evaluates each run, how many runs it has used against its limit, what it has spent against its money budget, its deadline, and the last verdict. ANSWER_IN_CHAT (default true) says whether each run's answer is posted into the conversation that made the trigger, under its card; NOTIFY (default false) says whether the person is also told through OpenVibe's notifications. UNDO_UNTIL is the end of the ten-minute undo window; after it the trigger is deleted, not undone. A trigger is owner-only: another person's id is the same 404 as one that does not exist. A mention trigger listens only to the person's own words to their own agent, never anyone else's messages, never a room or a stream chat, and never the agent's own answers; matching is case-insensitive, on word boundaries, after Unicode normalisation.

Fields

FieldTypeRequiredDescriptionConstraints
idstringyes
  • pattern ^trg_[0-9A-HJKMNP-TV-Z]{26}$
ownerstringyes
  • pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$
agent_idstringyes
  • pattern ^agt_[0-9A-HJKMNP-TV-Z]{26}$
agent_namestring | null
  • maxLength 60
taskstringyes
  • minLength 1
  • maxLength 8000
kindenumyes
  • one of "schedule", "event", "goal", "mention"
whenobjectyes
  • no other fields
when.wordsstringyes
  • minLength 1
  • maxLength 300
when.cronstring | null
  • maxLength 120
when.timezonestring | null
  • maxLength 64
when.eventobject | null
when.mentionobject | nullThe phrases a mention trigger waits for, and whether one or all of them must appear. Present only for kind mention; matching is case-insensitive, on word boundaries, after Unicode normalisation.
goalobject | nullA goal trigger's progress: what it keeps working toward and how far it has got. Null for a schedule or event trigger.
answer_in_chatbooleanWhether each run's answer is posted into the conversation that made the trigger, under its card. Default true.
  • default true
notifybooleanWhether the person is also told through OpenVibe's notifications when a run finishes. Default false: the answer in the chat is the telling, unless they asked for more.
  • default false
firesenumHow often the trigger may fire. In v1 the only value is once_per_conversation: at most once in each conversation. Optional; absent means the same.
  • one of "once_per_conversation"
  • default "once_per_conversation"
expires_atstring | nullWhen a mention trigger stops listening: required for kind mention and at most 90 days after created_at (the default is 30). JSON Schema cannot compare expires_at with created_at, so Actor enforces the 90-day cap; test/run.js checks the fixtures and the rule. Null or absent for other kinds.
  • format date-time
next_run_atstring | null
  • format date-time
last_runobject | null
stateenumyes
  • one of "active", "paused", "done"
paused_reasonenum
  • one of "person", "failed", "done", "budget", "deadline", null
failuresinteger
  • minimum 0
  • maximum 100
watchobject | null
undo_untilstring | null
  • format date-time
created_atstringyes
  • format date-time
updated_atstringyes
  • format date-time

Examples

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

Valid: event
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VX",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": null,
  "task": "triage the new issue",
  "kind": "event",
  "when": {
    "words": "When a new issue lands in openvibe/actor",
    "cron": null,
    "timezone": null,
    "event": {
      "pattern": "github.issue.opened",
      "filter": {
        "subject.id": "openvibe/actor"
      }
    }
  },
  "next_run_at": null,
  "last_run": {
    "task_id": "tsk_01M6VNTQD7VN1GGME3XGPJ049A",
    "state": "needs_you",
    "at": "2026-11-09T09:00:00.000Z",
    "error": null
  },
  "state": "paused",
  "paused_reason": "failed",
  "failures": 5,
  "watch": null,
  "undo_until": null,
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T09:00:00.000Z"
}
Valid: goal
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VW",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the price of the Framework 13 and say whether it is under €120",
  "kind": "goal",
  "when": {
    "words": "Every 30 minutes (Europe/Berlin)",
    "cron": "*/30 * * * *",
    "timezone": "Europe/Berlin",
    "event": null
  },
  "goal": {
    "text": "keep checking the price of the Framework 13 every 30 minutes until it drops under €120",
    "done_test": "the price of the Framework 13 is under €120",
    "runs_used": 4,
    "runs_max": 12,
    "spent_usd": 0.021,
    "budget_usd": 1.5,
    "deadline_at": "2026-11-16T09:00:00.000Z",
    "not_yet": "€134",
    "verdict": {
      "done": false,
      "reason": "€134 on the maker's own store",
      "at": "2026-11-09T10:30:20.000Z"
    }
  },
  "answer_in_chat": true,
  "notify": true,
  "next_run_at": "2026-11-09T11:00:00.000Z",
  "last_run": {
    "task_id": "tsk_01M6VNTQD7VN1GGME3XGPJ048Z",
    "state": "ok",
    "at": "2026-11-09T10:30:20.000Z"
  },
  "state": "done",
  "paused_reason": "done",
  "failures": 0,
  "watch": {
    "id": "wch_01M6VNTQD796C68VF8B182VAGS",
    "status": "paused",
    "last_state": "condition_met",
    "consecutive_failures": 0,
    "next_due_at": null
  },
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T10:30:21.000Z"
}
Valid: mention-all
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VZ",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release and the rollback",
    "mention": {
      "phrases": [
        "release",
        "rollback plan"
      ],
      "match": "all"
    }
  },
  "fires": "once_per_conversation",
  "expires_at": "2027-02-07T08:00:00.000Z",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Valid: mention-any
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VY",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release",
    "mention": {
      "phrases": [
        "the release",
        "shipping"
      ],
      "match": "any"
    }
  },
  "fires": "once_per_conversation",
  "expires_at": "2026-12-08T08:00:00.000Z",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Valid: schedule
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VW",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Inbox",
  "task": "summarise my inbox",
  "kind": "schedule",
  "when": {
    "words": "Every weekday at 09:00 (Europe/Berlin)",
    "cron": "0 9 * * 1-5",
    "timezone": "Europe/Berlin",
    "event": null
  },
  "next_run_at": "2026-11-10T08:00:00.000Z",
  "last_run": {
    "task_id": "tsk_01M6VNTQD7VN1GGME3XGPJ048Z",
    "state": "ok",
    "at": "2026-11-09T08:00:12.000Z"
  },
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "watch": {
    "id": "wch_01M6VNTQD796C68VF8B182VAGS",
    "status": "active",
    "last_state": "condition_met",
    "consecutive_failures": 0,
    "next_due_at": "2026-11-10T08:00:00.000Z"
  },
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: bad-kind
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VW",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Inbox",
  "task": "summarise my inbox",
  "kind": "whenever",
  "when": {
    "words": "Every weekday at 09:00 (Europe/Berlin)",
    "cron": "0 9 * * 1-5",
    "timezone": "Europe/Berlin",
    "event": null
  },
  "next_run_at": "2026-11-10T08:00:00.000Z",
  "last_run": {
    "task_id": "tsk_01M6VNTQD7VN1GGME3XGPJ048Z",
    "state": "ok",
    "at": "2026-11-09T08:00:12.000Z"
  },
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "watch": {
    "id": "wch_01M6VNTQD796C68VF8B182VAGS",
    "status": "active",
    "last_state": "condition_met",
    "consecutive_failures": 0,
    "next_due_at": "2026-11-10T08:00:00.000Z"
  },
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: goal-no-done-test
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VW",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "task": "keep checking the price",
  "kind": "goal",
  "when": {
    "words": "Every 30 minutes (Europe/Berlin)",
    "cron": "*/30 * * * *",
    "timezone": "Europe/Berlin"
  },
  "goal": {
    "text": "the price drops",
    "runs_used": 1
  },
  "state": "active",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: mention-bad-fires
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6W3",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release",
    "mention": {
      "phrases": [
        "the release",
        "shipping"
      ],
      "match": "any"
    }
  },
  "fires": "always",
  "expires_at": "2026-12-08T08:00:00.000Z",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: mention-no-expiry
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6W2",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release",
    "mention": {
      "phrases": [
        "the release",
        "shipping"
      ],
      "match": "any"
    }
  },
  "fires": "once_per_conversation",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: mention-one-character-phrase
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6W0",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release",
    "mention": {
      "phrases": [
        "x"
      ],
      "match": "any"
    }
  },
  "fires": "once_per_conversation",
  "expires_at": "2026-12-08T08:00:00.000Z",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: mention-six-phrases
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6W1",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Deals",
  "task": "check the release's rollback plan and say whether it can be rolled back",
  "kind": "mention",
  "when": {
    "words": "When you mention the release",
    "mention": {
      "phrases": [
        "release",
        "rollback",
        "ship",
        "deploy",
        "launch",
        "version"
      ],
      "match": "any"
    }
  },
  "fires": "once_per_conversation",
  "expires_at": "2026-12-08T08:00:00.000Z",
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}
Rejected: no-when
{
  "id": "trg_01M6VNTQD7NB3QH8K4R2S9T6VW",
  "owner": "usr_01M6VNTQD7MRZDETZ39NB969XD",
  "agent_id": "agt_01M6VNTQD7WHPRX74687KCER4S",
  "agent_name": "Inbox",
  "task": "summarise my inbox",
  "kind": "schedule",
  "next_run_at": "2026-11-10T08:00:00.000Z",
  "last_run": {
    "task_id": "tsk_01M6VNTQD7VN1GGME3XGPJ048Z",
    "state": "ok",
    "at": "2026-11-09T08:00:12.000Z"
  },
  "state": "active",
  "paused_reason": null,
  "failures": 0,
  "watch": {
    "id": "wch_01M6VNTQD796C68VF8B182VAGS",
    "status": "active",
    "last_state": "condition_met",
    "consecutive_failures": 0,
    "next_due_at": "2026-11-10T08:00:00.000Z"
  },
  "undo_until": "2026-11-09T08:10:00.000Z",
  "created_at": "2026-11-09T08:00:00.000Z",
  "updated_at": "2026-11-09T08:00:00.000Z"
}

Validate

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