PublishedDocs / Augments

Notify

Send a bounded outbound alert to an operator-selected file or remote destination.

Move an important event outside chat

What it enables

Let the agent escalate or report an event to a named operator destination without turning that channel into an inbound conversation.

Status: Stable
Availability: Add with `auggy augment add notify`; the default destination writes a local JSONL file.

Contributes

notify tool4 outbound adaptersrate and dedup policyadmin controls

Notify is for out-of-band operational messages: an escalation, requested status update, or event that needs human attention. It is not email conversation management, Telegram ingress, or a general queue.

Start with the local destination

Add Notifybash

auggy augment add notify

augments/notify/augment.yamlyaml

type: notify
config:
  destinations:
    - name: creator
      transport: log-to-file
      path: ./data/notifications.jsonl
      allowedTrustLevels:
        - creator
        - agent
  rateLimit:
    cooldownMs: 120000
    globalMaxPerHour: 5
    dedupWindowMs: 300000
    dedupThreshold: 0.6
    perPeerCooldownMs: 30000

Replace or extend `destinations` with `webhook`, `telegram`, or `agentmail` adapters when local JSONL is no longer enough. Keep destination credentials in environment variables.

Escalate one operational event

notify inputjson

{
  "to": "creator",
  "summary": "Checkout smoke test failed after the staging deploy.",
  "reason": "The release should not be promoted until the failure is reviewed."
}

The result is `sent`, `rate_limited`, or `failed`. For remote adapters, `sent` means the adapter or provider accepted the message; it is not a read receipt or proof that a person acted on it.

Runtime surfaces

Surface	Behavior
`notify({ to, summary, reason?, visitor? })`	Sends one concise message to a configured destination name.
`log-to-file`	Appends one JSON record to the configured file.
`webhook`	Posts a JSON payload to the configured endpoint.
`telegram`	Calls Telegram `sendMessage` for a configured chat.
`agentmail`	Sends new outbound email through configured AgentMail credentials.
Admin	Reports destinations and recent outcomes and supports a persistent daily-cap override.
Inbound	None. Notify never creates an Auggy turn from a response.

Production boundaries

Destinations default to `creator` and `agent` trust. Admitting `public` requires explicit policy and can require an escalation reason.
Creator calls bypass notification rate limits. Rate and dedup state for other peers is process-local, resets on restart, and is not coordinated across replicas.
Failed delivery does not consume quota. Successful remote API acceptance does not prove human delivery or reading.
Recent events are in memory. The local JSONL destination and admin cap override persist; remote providers own their delivery records.
Use the separate AgentMail augment for email conversations, including inbound turns, replies, and forwarding, and Telegram Transport for bidirectional Telegram chat; Notify remains outbound-only.

Verify before adding a remote adapter

1Keep the generated `log-to-file` destination and start the agent as creator.
2Ask for the test notification above and confirm the tool returns `sent`.
3Inspect `data/notifications.jsonl` and confirm it contains one bounded event without provider secrets.
4Repeat from a `public` auth context and confirm the destination trust policy denies the call.
5After configuring a remote adapter, repeat once and verify both the Auggy result and the provider-side delivery record.

Add an augmentInstall layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.AgentMailGive an agent a policy-gated inbox with durable inbound delivery, send, reply, and forward tools, creator review, and recovery.TelegramRun text turns through a Telegram bot with polling or webhooks and static operator-configured identity lists.Add toolsExpose typed actions the model can select during a turn and your code executes.SecurityAuggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.