Workflow Trigger And Payload Contract

Workflows can start through four driver families. A direct browser, API v1, or Action call supplies the caller’s optional payload and records its actor type. Cron’s workflow_run target supplies cronJobId, scheduledFor, message, metadata, firedAt, timezone, localDate, localTime, localWeekday, and localDateTime. Local values are calculated from the scheduled occurrence in the job timezone. Web and API v1 may create this target without an Agent, while the Cron Action remains bound to its calling Agent. An inbound Webhook run_workflow function passes the accepted JSON body. A generic Trigger with target workflow_run remains Agent-bound, passes its durable fire-event payload, and uses that fire-event ID as the run idempotency key. See the full Platform Cron contract.

Trigger targets deliberately remain a strict subset of Cron targets: agent_wakeup, conversation_message, and workflow_run. Cron-only notify, outbound_delivery, and action_call are not accepted by Trigger create, update, or dispatch, and this vocabulary difference does not alter existing Trigger ownership, Agent anchoring, quota, or delivery behavior.

Direct, Webhook, Trigger, and Cron inputs are limited to 102,400 serialized JSON bytes. An over-limit direct request returns PAYLOAD_TOO_LARGE; an over-limit Trigger or Cron delivery is skipped with workflow_payload_too_large. Trigger delivery reports distinct terminal reasons for a missing target ID, a deleted Workflow, a paused Workflow, and invalid payload. Workflow hourly rate limits are retryable through the durable Trigger outbox and its existing attempt cap and backoff. Cron uses the same shared Workflow executor: a rate-limited scheduled occurrence or manual run is retryable without consuming a fire event or idempotency key, and the retry must reuse the same deterministic key.

Trigger debounce preserves the anchor payload and adds an ordered events array containing each fire-event payload in the merged window. If that envelope would exceed 102,400 bytes, events are removed from the tail until it fits and eventsTruncated: true is added. The stable Trigger sourceRef and its rate-limit hash do not change.

Manual and Cron runs begin with chainDepth: 0. The Trigger workflow target passes depth through unchanged. When a Workflow reaches a terminal state, its event emitter increments depth exactly once; Trigger matching rejects depth 3 or greater with chain_depth_exceeded. Creating or updating a Trigger whose Workflow source and Workflow target are the same ID returns TRIGGER_SELF_REFERENCE. Event-started Agent instructions are wrapped in an <arinova-trigger> envelope and treated as untrusted event-derived text.

Run details expose chainDepth, actorType, actorId, and sourceFireEventId; a Cron actor links back to its schedule. Historical rows without actor provenance report unknown. A created run is not proof of completion: inspect the run and step-run terminal statuses. Message steps support H2A and group conversations on the ordinary Chat surface only, post a system/completed message through the shared realtime, unread, and push path, and allow 50 Workflow notifier messages per conversation in a rolling 24-hour window. The Workflow owner is recorded as the sender, so that owner’s own sessions receive the durable message through realtime/sync but do not receive a self-authored push or notification-center entry; other eligible members follow their normal conversation notification policy.

Platform Agent steps are owner-bound: the referenced Agent must belong to the Workflow owner even when that Agent is public. Validation returns PLATFORM_AGENT_OWNER_REQUIRED (HTTP 403), and execution-time revalidation records platform_agent_owner_required if ownership changes after publication. Public external Agents retain their existing compatibility behavior.