# Notify

Canonical: https://auggy.dev/docs/augment-notify
Status: Published
Package: auggy 0.5.0

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 tool`, `4 outbound adapters`, `rate and dedup policy`, `admin 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 Notify**

```bash
auggy augment add notify
```

**augments/notify/augment.yaml**

```yaml
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 input**

```json
{
  "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

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

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [AgentMail](https://auggy.dev/docs/augment-agentmail/markdown)
- [Telegram](https://auggy.dev/docs/augment-telegram/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Security](https://auggy.dev/docs/security/markdown)