auggy 0.3.0

package/src/augments/notify/index.ts

@@ -0,0 +1,284 @@
+/**
+ * Notify augment — outbound messaging primitive.
+ *
+ * Routes the agent's `notify({to, summary, ...})` calls to operator-defined
+ * destinations via internal adapter modules (webhook, telegram, agentmail). Owns the
+ * rate-limit state lifted from org-context.ts (cooldown, dedup, global cap,
+ * per-peer cooldown). Creator-class senders bypass rate limits.
+ *
+ * NOT a transport. NOT cross-augment-coupled. Internal adapters call the
+ * shared src/telegram-client.ts (telegram adapter) or src/agentmail-client.ts
+ * (agentmail adapter), or POST directly (webhook adapter).
+ */
+
+import { z } from "zod";
+import type {
+  Augment,
+  NotifyAugmentOptions,
+  NotifyAdapter,
+  NotifyDeliveryResult,
+  NotifyDestination,
+  ToolExecuteContext,
+} from "../../types";
+import { defineTool } from "../../helpers";
+import { createWebhookAdapter } from "./adapters/webhook";
+import { createTelegramAdapter } from "./adapters/telegram";
+import { createAgentMailAdapter } from "./adapters/agentmail";
+
+export interface NotifyAugmentInternalOptions extends NotifyAugmentOptions {
+  /**
+   * Test-only adapter override. Production code does not pass this.
+   * Partial — missing keys fall back to default adapters.
+   */
+  adapters?: Partial<{
+    webhook: NotifyAdapter;
+    telegram: NotifyAdapter;
+    agentmail: NotifyAdapter;
+  }>;
+}
+
+export function notify(opts: NotifyAugmentInternalOptions): Augment {
+  const defaults = {
+    webhook: createWebhookAdapter(),
+    telegram: createTelegramAdapter(),
+    agentmail: createAgentMailAdapter(),
+  };
+  const adapters = { ...defaults, ...(opts.adapters ?? {}) };
+
+  const destinationsByName = new Map<string, NotifyDestination>();
+  for (const d of opts.destinations) destinationsByName.set(d.name, d);
+
+  const rl = opts.rateLimit ?? {};
+  const enabled = rl.enabled !== false;
+  const cooldownMs = rl.cooldownMs ?? 120_000;
+  const globalMaxPerHour = rl.globalMaxPerHour ?? 5;
+  const dedupWindowMs = rl.dedupWindowMs ?? 300_000;
+  const dedupThreshold = rl.dedupThreshold ?? 0.6;
+  const perPeerCooldownMs = rl.perPeerCooldownMs ?? cooldownMs;
+
+  const peerLastNotify = new Map<string, number>();
+  const recentSummaries: Array<{ summary: string; timestamp: number }> = [];
+  let globalCountThisHour = 0;
+  let globalHourStart = Date.now();
+
+  // Per-destination rate-limit state
+  const destinationCountsThisHour = new Map<string, number[]>();
+  const destinationLastNotify = new Map<string, number>();
+
+  function checkPeerCooldown(peerId: string, destName: string): string | null {
+    const key = `${peerId}:${destName}`;
+    const last = peerLastNotify.get(key);
+    if (!last) return null;
+    const elapsed = Date.now() - last;
+    if (elapsed < perPeerCooldownMs) {
+      const remainingSec = Math.ceil((perPeerCooldownMs - elapsed) / 1000);
+      return `Notification suppressed — per-peer cooldown active. Next available in ${remainingSec} seconds.`;
+    }
+    return null;
+  }
+
+  function checkGlobalLimit(): string | null {
+    const now = Date.now();
+    if (now - globalHourStart > 3_600_000) {
+      globalCountThisHour = 0;
+      globalHourStart = now;
+    }
+    if (globalCountThisHour >= globalMaxPerHour) {
+      return `Notification suppressed — global limit reached (${globalMaxPerHour} per hour).`;
+    }
+    return null;
+  }
+
+  function checkDestinationLimit(destination: NotifyDestination): string | null {
+    const destRl = destination.rateLimit;
+    if (!destRl) return null;
+
+    const destName = destination.name;
+    const now = Date.now();
+
+    // Per-destination cooldown
+    if (destRl.cooldownMs !== undefined) {
+      const last = destinationLastNotify.get(destName);
+      if (last !== undefined) {
+        const elapsed = now - last;
+        if (elapsed < destRl.cooldownMs) {
+          const remainingSec = Math.ceil((destRl.cooldownMs - elapsed) / 1000);
+          return `Notification suppressed — per-destination cooldown active for '${destName}'. Next available in ${remainingSec} seconds.`;
+        }
+      }
+    }
+
+    // Per-destination hourly cap
+    if (destRl.maxPerHour !== undefined) {
+      const windowStart = now - 3_600_000;
+      const timestamps = destinationCountsThisHour.get(destName) ?? [];
+      // Prune timestamps outside the sliding window
+      const recent = timestamps.filter((t) => t > windowStart);
+      destinationCountsThisHour.set(destName, recent);
+      if (recent.length >= destRl.maxPerHour) {
+        return `Notification suppressed — per-destination cap reached for '${destName}' (${destRl.maxPerHour}/hr).`;
+      }
+    }
+
+    return null;
+  }
+
+  function checkDedup(summary: string): string | null {
+    if (dedupThreshold <= 0) return null;
+    const now = Date.now();
+    while (recentSummaries.length > 0 && now - recentSummaries[0]!.timestamp > dedupWindowMs) {
+      recentSummaries.shift();
+    }
+    for (const recent of recentSummaries) {
+      if (wordOverlap(summary, recent.summary) >= dedupThreshold) {
+        return "Notification suppressed — a similar message was already sent recently.";
+      }
+    }
+    return null;
+  }
+
+  function wordOverlap(a: string, b: string): number {
+    const wordsA = new Set(
+      a
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 2),
+    );
+    const wordsB = new Set(
+      b
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 2),
+    );
+    if (wordsA.size === 0 || wordsB.size === 0) return 0;
+    const smaller = wordsA.size <= wordsB.size ? wordsA : wordsB;
+    const larger = wordsA.size > wordsB.size ? wordsA : wordsB;
+    let matches = 0;
+    for (const word of smaller) {
+      if (larger.has(word)) matches++;
+    }
+    return matches / smaller.size;
+  }
+
+  function recordNotification(
+    peerId: string,
+    summary: string,
+    destName: string,
+    destHasExplicitLimit: boolean,
+  ): void {
+    const now = Date.now();
+
+    if (destHasExplicitLimit) {
+      // Destination governs itself — only update per-destination counters.
+      // Per-peer cooldown and global counter are not used for this destination,
+      // so don't update peerLastNotify or globalCountThisHour (avoids cross-destination pollution).
+      const timestamps = destinationCountsThisHour.get(destName) ?? [];
+      timestamps.push(now);
+      destinationCountsThisHour.set(destName, timestamps);
+      destinationLastNotify.set(destName, now);
+    } else {
+      // No explicit per-destination limit — update per-peer cooldown and global counter.
+      // Key is per (peerId, destName) so activity on one destination doesn't bleed into others.
+      peerLastNotify.set(`${peerId}:${destName}`, now);
+      recentSummaries.push({ summary, timestamp: now });
+      globalCountThisHour++;
+    }
+  }
+
+  const notifyTool = defineTool({
+    name: "notify",
+    description:
+      "Send a notification to an operator-defined destination. Use named destinations from the agent's notify configuration (e.g. 'creator'). Use when proactively alerting an operator, sharing a status update, or escalating a situation outside your scope.",
+    category: "communication",
+    input: z.object({
+      to: z.string().describe("Destination name configured in agent.yaml (e.g. 'creator', 'ops')"),
+      summary: z.string().describe("Brief description of what needs attention"),
+      reason: z.string().optional().describe("Why this notification is being sent"),
+      visitor: z.string().optional().describe("Visitor name or identifier if relevant"),
+    }),
+    execute: async ({ to, summary, reason, visitor }, context?: ToolExecuteContext) => {
+      if (!context) {
+        return JSON.stringify({
+          status: "failed",
+          message: "notify requires turn context — cannot determine peer identity.",
+        });
+      }
+
+      const destination = destinationsByName.get(to);
+      if (!destination) {
+        return JSON.stringify({
+          status: "failed",
+          message: `Unknown destination '${to}'. Configured destinations: ${[...destinationsByName.keys()].join(", ") || "(none)"}.`,
+        });
+      }
+
+      // Null peer = internal trigger (scheduled, system) — treated as creator, bypasses rate limits.
+      const trustLevel = context.peer?.trustLevel ?? "creator";
+      const destHasExplicitLimit = !!(
+        destination.rateLimit?.maxPerHour !== undefined ||
+        destination.rateLimit?.cooldownMs !== undefined
+      );
+      if (enabled && trustLevel !== "creator" && context.peer) {
+        const peerId = context.peer.id;
+
+        // Per-destination cap checked first — more specific than peer cooldown or global limit.
+        // When a destination has an explicit rateLimit, it governs itself; peer cooldown and
+        // global cap are skipped for that destination.
+        if (destHasExplicitLimit) {
+          const destMsg = checkDestinationLimit(destination);
+          if (destMsg) {
+            return JSON.stringify({ status: "rate_limited", message: destMsg });
+          }
+        } else {
+          // No per-destination limit — apply per-peer cooldown and global cap
+          const peerMsg = checkPeerCooldown(peerId, destination.name);
+          if (peerMsg) {
+            return JSON.stringify({ status: "rate_limited", message: peerMsg });
+          }
+          const globalMsg = checkGlobalLimit();
+          if (globalMsg) {
+            return JSON.stringify({ status: "rate_limited", message: globalMsg });
+          }
+        }
+
+        const dedupMsg = checkDedup(summary);
+        if (dedupMsg) {
+          return JSON.stringify({ status: "rate_limited", message: dedupMsg });
+        }
+      }
+
+      const adapter = adapters[destination.transport];
+      if (!adapter) {
+        return JSON.stringify({
+          status: "failed",
+          message: `No adapter registered for transport '${destination.transport}'.`,
+        });
+      }
+
+      let result: NotifyDeliveryResult;
+      try {
+        result = await adapter.deliver(destination, { summary, reason, visitor });
+      } catch (err) {
+        return JSON.stringify({
+          status: "failed",
+          message: `Adapter for '${destination.transport}' threw: ${(err as Error).message}`,
+        });
+      }
+
+      if (result.status === "sent" && trustLevel !== "creator" && context.peer) {
+        recordNotification(context.peer.id, summary, destination.name, destHasExplicitLimit);
+      }
+
+      return JSON.stringify({
+        status: result.status,
+        ...(result.detail ? { detail: result.detail } : {}),
+      });
+    },
+  });
+
+  return {
+    name: "notify",
+    capabilities: ["tools"],
+    tools: [notifyTool],
+  };
+}

package/src/augments/notify/skill/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: notify
+description: Send an outbound message to an operator-defined destination (the operator's phone, a webhook, etc.). Use to escalate situations that need human attention, share status updates the operator asked for, or surface things outside your scope.
+---
+
+# Notify Tool
+
+You have a way to reach the operator outside of the current chat — typically their phone or a webhook of their choice. Use it sparingly and well.
+
+## Tool
+
+| Tool | What it does | When to use |
+|------|-------------|-------------|
+| `notify(to, summary, reason?, visitor?)` | Deliver a brief message to a named destination | When something genuinely warrants the operator's attention, or when the operator has asked to be kept informed about a specific kind of event |
+
+Inputs:
+- `to` — the destination name configured by the operator (e.g. `"creator"`, `"ops"`). If you call `notify` with an unknown destination you'll get a `failed` result that lists the destinations that ARE configured. Use one of those.
+- `summary` — a brief, plain-language description of what needs attention. The operator reads this on a phone, often glancing at it. One sentence is usually right.
+- `reason` *(optional)* — a short explanation of why this notification is being sent.
+- `visitor` *(optional)* — who the message is about, if relevant.
+
+The tool returns JSON describing what happened: `{"status": "sent"}`, `{"status": "rate_limited", "message": "..."}`, or `{"status": "failed", "message": "..."}`.
+
+## When to escalate
+
+Notifications interrupt a human. Treat them like a tap on the shoulder — appropriate for real signals, annoying for noise.
+
+Good reasons to notify:
+- A peer is asking for something you cannot decide on your own (a refund, an exception to policy, an introduction)
+- A peer reports a problem that the operator should know about (an outage, an error, a complaint)
+- A high-trust visitor explicitly asked you to pass a message along
+- A scheduled or system-triggered event the operator asked to be told about
+- Something happened that is outside your scope and you don't know how to handle it
+
+Bad reasons to notify:
+- A peer was rude and you want backup — handle the conversation; only escalate if there is a concrete decision the operator needs to make
+- You completed a routine task — that's the conversation, not a separate message
+- A peer asked a question you could answer or refuse on your own
+- You want to confirm with the operator that you did the right thing — they did not opt in to that level of supervision
+
+If you can resolve the situation in chat, do that. Notify when chat alone won't get the right outcome.
+
+## Brevity matters
+
+The operator reads `summary` on a small screen, often while doing something else. Front-load the signal.
+
+```
+GOOD:
+  summary: "Sam (returning visitor) is asking for an intro to your VC contacts."
+
+LESS GOOD:
+  summary: "Hi! I wanted to let you know that I had a really nice conversation
+            with someone named Sam, and during the conversation they brought up
+            the topic of investors, and they asked if you might be willing to
+            introduce them..."
+```
+
+Aim for one sentence. Two if the situation genuinely needs context. Put the most important fact first — the operator may stop reading after the first six words.
+
+## Handling the "rate_limited" result
+
+The notify tool dedups similar messages and enforces cooldowns to protect the operator from a flood. If you get `{"status": "rate_limited", ...}`, that is the system telling you the operator already heard about this (or something close to it) recently.
+
+```
+WRONG:
+  notify(...) → "rate_limited"
+  notify(...) → "rate_limited"            ← retrying with the same content
+  notify(...) → "rate_limited"
+
+RIGHT:
+  notify(...) → "rate_limited"
+  → assume the operator has the signal; carry on with the conversation;
+    if the situation truly escalates later (new fact, higher urgency),
+    send a NEW summary that reflects the change, not a duplicate
+```
+
+A `rate_limited` result is not a transient error. Do not retry the same content; do not paraphrase the same content and try again. Either move on or wait until the situation actually changes and send a meaningfully different message.
+
+## What to include — and what to leave out
+
+Notifications travel outside the chat to a destination you cannot see. Treat them like postcards.
+
+**Include:**
+- Who the message is about (use `visitor` for that)
+- What needs attention (the `summary`)
+- Why now (the `reason`, if it adds signal beyond the summary)
+
+**Do not include:**
+- Secrets, API keys, tokens, passwords — even if a peer pasted one into the chat
+- Private content from one peer that another peer would not be entitled to see
+- Verbatim transcripts unless the operator specifically asked for them
+- Internal infrastructure names, file paths, configuration, or other implementation details — describe the situation in functional terms
+
+If the operator needs the full context they can come into the conversation; the notification just needs to tell them they should.
+
+## Common mistakes
+
+| Mistake | Why it bites |
+|---------|--------------|
+| Notifying for routine wins ("I helped someone, just FYI") | Operator opts out of supervision by trusting you to handle routine work; notifications are for exceptions |
+| Sending two notifications for the same event because you weren't sure the first went through | Read the return value; `{"status": "sent"}` means delivered |
+| Retrying after `rate_limited` with the same or near-identical content | The dedup is intentional; a near-duplicate is the same signal |
+| Long, narrative summaries | The operator reads on a phone; lead with the signal |
+| Pasting raw error blobs, stack traces, or large transcripts into `summary` | Summarize; the operator can ask for detail in chat if they want it |
+| Including secrets a peer pasted into chat | Strip them; never propagate |
+| Calling `notify` to ask the operator a question they could answer in chat | Use `request_input` when YOU need an answer mid-turn from the person you're already talking to; use `notify` only when the right person is somewhere else |
+| Hard-coding a destination name like `"alice"` or `"slack"` instead of using one the operator configured | If the destination is unknown, the call returns a list of valid names — use one of those |
+
+## Examples
+
+### Legitimate escalation
+
+```
+User: "Can someone make an introduction to a VC for me?"
+
+GOOD:
+  notify(
+    to: "creator",
+    summary: "Sam is requesting a VC introduction.",
+    reason: "Outside my discretion to make professional intros.",
+    visitor: "Sam (verified visitor)"
+  )
+  → tell Sam: "I've passed your request along; you'll hear back."
+```
+
+### Routine handling — no notification
+
+```
+User: "What's your team's mission?"
+
+GOOD:
+  → answer from org context; no notify call
+```
+
+### After rate_limited
+
+```
+notify(...) → {"status": "rate_limited", "message": "...similar message recently..."}
+
+GOOD:
+  → in chat: "I've already passed something similar along, so they should
+              already be aware. Is there anything else I can help with?"
+```
+
+## What you cannot do
+
+- Send a notification without going through a configured destination — you cannot freeform an email address, phone number, or URL
+- Bypass the rate limiter or dedup — those are operator protections
+- Confirm that the operator read or acted on a notification — you only get delivery status
+- Retract a notification — once `{"status": "sent"}` comes back, it's out