@helloaigent-dev/subscriber
The Hello Aigent reference subscriber — an MCP server that lets any agent subscribe to any Hello Aigent feed, fetch signed updates, verify them, and act on them. Plus watch mode: a standing poller that collects verified updates into a digest between agent runs.
npx @helloaigent-dev/subscriber # MCP server (stdio)
npx @helloaigent-dev/subscriber watch # standing watcher (default cadence: daily)
Tools
| Tool | What it does |
|---|---|
hello_aigent_subscribe(discovery_url, feed_id?, principal?, consent_scope?) | Reads the site's /.well-known/hello-aigent.json, subscribes (defaults come from your policy) |
hello_aigent_fetch(subscription_id?, max?) | Pulls only-new-since updates via the stored cursor; verifies every envelope signature |
hello_aigent_unsubscribe(subscription_id) | Revokes consent (idempotent) — the one-call undo |
hello_aigent_list_subscriptions() | Lists stored subscriptions (tokens are never exposed) |
hello_aigent_check_site(url) | Checks a site you're visiting for a feed; auto-subscribes per your standing policy (origin: auto) |
hello_aigent_digest() | Returns unread digest entries collected by watch and marks them surfaced |
hello_aigent_setup_watch(cadence?) | Emits ready-to-apply standing-schedule recipes (scheduled task, recurring task, cron) |
Watch mode
npx @helloaigent-dev/subscriber watch --once # one pass (what schedulers call)
npx @helloaigent-dev/subscriber watch --every 6h # long-running loop (floor: hourly)
npx @helloaigent-dev/subscriber watch --once --exec "my-agent-cmd" # trigger a run on new updates
Each pass polls every active subscription, verifies signatures, and appends new updates to the
digest file. The server-side mailbox means a missed run loses nothing. --exec runs your command
when new updates land, with HELLO_AIGENT_NEW_UPDATES and HELLO_AIGENT_DIGEST set.
Policy
Written to ~/.hello-aigent/policy.json on first run — everything automatic by default, and this
file is where you change that:
| Key | Default | Meaning |
|---|---|---|
principal | user@host | Your stable identity across all feeds — set it once (e.g. your email) |
auto_subscribe | on | Subscribe when your agent visits a Hello Aigent site: on / ask / off |
watch_cadence | daily | How often watch polls (hourly floor) |
act | safe | What the agent may do unprompted: none / safe (side-effect-free) / thresholds |
pseudonymous | false | Opt-in: per-site pseudonymous principals |
Feeds nobody reads decay: after 30 idle days watch stops polling them; after 60 it unsubscribes (noted in the digest). Reading the digest or fetching a feed keeps it alive.
Guarantees
- Signature verification before anything is actionable. Envelopes are Ed25519-verified
(RFC 8785 JCS canonicalization) against the feed's discovery public key. Anything that fails
verification is returned under
unverifiedwith itsactionsstripped. - Consent is standing policy. Subscribing records
principal+consent_scope; your policy file is the consent layer, and unsubscribe is always one idempotent call. - Local state only. Subscriptions (including bearer tokens), policy, and the digest live in
~/.hello-aigent/(mode 0600). Override withHELLO_AIGENT_STATE/HELLO_AIGENT_POLICY/HELLO_AIGENT_DIGEST.
MCP client config
{
"mcpServers": {
"hello-aigent": { "command": "npx", "args": ["@helloaigent-dev/subscriber"] }
}
}
License
MIT