defineWatch, describeWatch, and DurableWatch are exported by @agentium/harness. Definitions are pure JSON operations. Constructing a watch does not subscribe to anything; work begins with an explicit activate() call.
For complete package documentation, including configuration, lifecycle methods, defaults, and examples, see @agentium/harness durable watches and the watch API reference.
Supply host services
A watch needs a durable task store, source adapter, persistent scheduler, scoped notification connector, authorizer, and deterministic filter. The optionalgmailWatchSource accepts an already authenticated Gmail client and explicit push verifier. It loads no credentials or Google SDK by itself.
Host authorization checks verified tenant/actor identity, source access, fixed channel/destination, policy revision, grants, and requested amounts. Grant references are not authority by themselves. This implementation uses deterministic filters and makes no model calls.
Process changes
trigger(raw) authenticates the source hint, checks principal/scope, and reads from the persisted cursor. A push-supplied cursor cannot advance state. Stable semantic event IDs deduplicate admission; unchanged wakes send nothing.
Cursor advancement and pending digest decisions commit together under a fenced lease. flush() prepares at most one digest, reserves the local-day notification cap, and sends through DurableActionLedger. Quiet hours and cooldowns use the configured IANA timezone and persist across restarts.
The scheduler stores idempotent, tenant-scoped poll, renew, and flush jobs and routes them to the correct watch version. Failed job publication leaves desired times in persisted state; repeating activation repairs scheduling. The host must actually run these scheduled methods.
Lifecycle
Unknown delivery blocks newer digests until the connector supplies durable evidence. Pause/delete never automatically resend pending work. Leases prevent stale commits but cannot retract an already-sent notification.