@helloaigent-dev/subscriber

@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 unverified with its actions stripped.
• 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 with HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST.

MCP client config

{
  "mcpServers": {
    "hello-aigent": { "command": "npx", "args": ["@helloaigent-dev/subscriber"] }
  }
}

License

MIT