Push notifications

from bindu.penguin.manifest import bindufy

config = {
    "name": "data-processor",
    "capabilities": {"push_notifications": True},   # required
    "global_webhook_url": "https://myapp.com/webhooks/global",  # optional fallback
    "global_webhook_token": "global_secret_token",              # optional
}

bindufy(config, handler)

import requests
from uuid import uuid4

resp = requests.post("http://localhost:3773/", json={
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "message/send",
    "params": {
        "message": {
            "message_id": str(uuid4()),
            "task_id": str(uuid4()),
            "context_id": str(uuid4()),
            "kind": "message",
            "role": "user",
            "parts": [{"kind": "text", "text": "Process large dataset"}],
        },
        "configuration": {
            "accepted_output_modes": ["application/json"],
            "long_running": True,
            "push_notification_config": {
                "id": str(uuid4()),
                "url": "https://myapp.com/webhooks/task-updates",
                "token": "secret_abc123",
            },
        },
    },
})
print(resp.json()["result"]["id"])

from fastapi import FastAPI, Request, Header, HTTPException

app = FastAPI()
EXPECTED = "Bearer secret_abc123"

@app.post("/webhooks/task-updates")
async def handle(request: Request, authorization: str = Header(None)):
    if authorization != EXPECTED:
        raise HTTPException(401)

    event = await request.json()
    kind = event["kind"]

    if kind == "status-update":
        state = event["status"]["state"]
        print(f"task {event['task_id']} -> {state}")
        # input-required / auth-required carry the prompt in status.message
        if state in ("input-required", "auth-required"):
            msg = event["status"].get("message", {})
            print("agent asks:", msg.get("parts", [{}])[0].get("text"))
        if event["final"]:
            print("terminal")

    elif kind == "artifact-update":
        print("artifact:", event["artifact"].get("name"))

    return {"ok": True}

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "sequence": 1,
  "timestamp": "2026-05-18T08:00:00.123456+00:00",
  "kind": "status-update",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "context_id": "789e0123-e89b-12d3-a456-426614174000"
}

POST /webhooks/task-updates HTTP/1.1
Host: myapp.com
Content-Type: application/json
Authorization: Bearer secret_abc123

POST / (message/send, long_running=true)
  -> register_push_config(persist=True)
  -> Storage.save_webhook_config
[ server crash + restart ]
  -> PushNotificationManager.initialize()
  -> Storage.load_all_webhook_configs() -> {task_id: config, ...}
  -> notifications resume

class PushNotificationConfig(TypedDict):
    id: Required[UUID]            # subscription ID — used for delete
    url: Required[str]            # http or https; private IPs rejected
    token: NotRequired[str]       # sent verbatim as "Authorization: Bearer <token>"
    authentication: NotRequired[SecurityScheme]  # optional richer auth schema

import hmac
from fastapi import FastAPI, Request, Header, HTTPException

app = FastAPI()
EXPECTED = "Bearer secret_abc123"

@app.post("/webhook")
async def hook(request: Request, authorization: str = Header(None)):
    if not authorization or not hmac.compare_digest(authorization, EXPECTED):
        raise HTTPException(401)
    return await _process(await request.json())

seen: set[str] = set()
last_seq: dict[str, int] = {}

async def _process(event):
    eid = event["event_id"]
    if eid in seen:
        return {"ok": True, "dedup": True}
    seen.add(eid)

    tid = event["task_id"]
    if event["sequence"] <= last_seq.get(tid, 0):
        # out-of-order or replay — fold into reconciliation pass, not state
        return {"ok": True, "stale": True}
    last_seq[tid] = event["sequence"]

    # ... do work ...
    return {"ok": True}

const express = require("express");
const app = express();
app.use(express.json());

const EXPECTED = "Bearer secret_abc123";

app.post("/webhook", (req, res) => {
  if (req.headers.authorization !== EXPECTED) {
    return res.status(401).json({ error: "unauthorized" });
  }
  const ev = req.body;
  if (ev.kind === "status-update") {
    console.log(`${ev.task_id} -> ${ev.status.state}${ev.final ? " (final)" : ""}`);
  } else if (ev.kind === "artifact-update") {
    console.log(`artifact ${ev.artifact.name} for ${ev.task_id}`);
  }
  res.json({ ok: true });
});

app.listen(8000);

curl -X POST https://myapp.com/webhooks/task-updates \
  -H "Authorization: Bearer secret_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "test-1",
    "sequence": 1,
    "timestamp": "2026-05-18T00:00:00+00:00",
    "kind": "status-update",
    "task_id": "11111111-1111-1111-1111-111111111111",
    "context_id": "22222222-2222-2222-2222-222222222222",
    "status": {"state": "working", "timestamp": "2026-05-18T00:00:00+00:00"},
    "final": false
  }'