aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/plugins/channel/adapters/telegram.py

@@ -0,0 +1,302 @@
+import asyncio
+import logging
+import os
+
+import httpx
+
+from aethergraph.contracts.services.channel import ChannelAdapter, OutEvent
+from aethergraph.services.continuations.continuation import Correlator
+
+
+def _tg_render_bar(percent: float, width: int = 20) -> str:
+    p = max(0.0, min(1.0, percent))
+    filled = int(round(p * width))
+    return "█" * filled + "░" * (width - filled)
+
+
+def _tg_fmt_eta(sec: float | None) -> str:
+    if sec is None:
+        return ""
+    s = int(max(0, sec))
+    if s < 60:
+        return f"{s}s"
+    m, s = divmod(s, 60)
+    if m < 60:
+        return f"{m}m {s}s"
+    h, m = divmod(m, 60)
+    return f"{h}h {m}m"
+
+
+def _prune(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _mk_params(chat_id: int, topic_id: int | None, **rest) -> dict:
+    p = {"chat_id": chat_id, **rest}
+    if topic_id is not None:
+        p["message_thread_id"] = topic_id
+    return p
+
+
+def _safe_text_md(text: str | None) -> tuple[str, str | None]:
+    """
+    Best-effort: if text looks like Markdown-safe, return ("Markdown", text).
+    Else, drop parse mode to avoid 400s on unescaped symbols.
+    """
+    if not text:
+        return "", "Markdown"
+    # very light check – if it contains risky characters unbalanced, avoid MD
+    risky = any(c in text for c in ("*", "_", "[", "`"))
+    return (text, None if risky else "Markdown")
+
+
+class TelegramChannelAdapter(ChannelAdapter):
+    """
+    Telegram channel adapter using the Bot API.
+    Channel key format:
+      - "tg:chat/<chat_id>"
+      - Optional topic (supergroups): "tg:chat/<chat_id>:topic/<message_thread_id>"
+    """
+
+    capabilities: set[str] = {"text", "buttons", "image", "file", "edit", "stream"}
+
+    def __init__(self, bot_token: str | None = None, *, timeout_s: int = 15):
+        self.token = bot_token or os.environ["TELEGRAM_BOT_TOKEN"]
+        self.base = f"https://api.telegram.org/bot{self.token}"
+
+        timeout = httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=30.0)
+        limits = httpx.Limits(
+            max_connections=20, max_keepalive_connections=10, keepalive_expiry=30.0
+        )
+
+        try:
+            transport = httpx.AsyncHTTPTransport(retries=0, local_address="0.0.0.0", http2=False)
+        except Exception:
+            transport = httpx.AsyncHTTPTransport(retries=0, http2=False)
+
+        # proxies = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY") or None
+
+        self._client = httpx.AsyncClient(timeout=timeout, limits=limits, transport=transport)
+        # cache for edit/upsert: (channel_key, upsert_key) -> (chat_id, message_id)
+        self._msg_id_cache: dict[tuple[str, str], tuple[int, int]] = {}
+
+    async def aclose(self):
+        try:
+            await self._client.aclose()
+        except Exception as e:
+            logger = logging.getLogger("aethergraph.plugins.channel.adapters.telegram")
+            logger.warning(f"Failed to close Telegram client: {e}")
+
+    # ------------- helpers -------------
+    @staticmethod
+    def _parse(channel_key: str) -> dict:
+        """
+        Parse "tg:chat/<chat_id>[:topic/<message_thread_id>]" → {"chat": int, "topic": int|None}
+        """
+        if not channel_key.startswith("tg:"):
+            raise ValueError(f"Not a telegram channel key: {channel_key}")
+        parts = channel_key.split(":")[1:]  # drop "tg"
+        d = {}
+        for p in parts:
+            k, v = p.split("/", 1)
+            d[k] = v
+        chat_id = int(d["chat"])
+        topic_id = int(d["topic"]) if "topic" in d else None
+        return {"chat": chat_id, "topic": topic_id}
+
+    async def _api(self, method: str, **params):
+        """POST to Telegram with retries on connect and 429, robust error handling."""
+        url = f"{self.base}/{method}"
+        files = params.pop("_files", None)
+
+        last_exc = None
+        for attempt in range(3):
+            try:
+                if files:
+                    resp = await self._client.post(url, data=_prune(params), files=files)
+                else:
+                    resp = await self._client.post(url, json=_prune(params))
+                resp.raise_for_status()
+                data = resp.json()
+                if not data.get("ok", False):
+                    if data.get("error_code") == 429:
+                        retry_after = (data.get("parameters") or {}).get("retry_after", 1)
+                        await asyncio.sleep(int(retry_after))
+                        continue
+                    desc = data.get("description", "Unknown Telegram error")
+                    raise RuntimeError(f"Telegram API error: {data.get('error_code')} {desc}")
+                return data
+            except httpx.ConnectError as e:
+                last_exc = e
+                await asyncio.sleep(0.6 * (attempt + 1))
+            except httpx.ReadTimeout as e:
+                last_exc = e
+                await asyncio.sleep(0.6 * (attempt + 1))
+            except ValueError as e:
+                text = getattr(resp, "text", lambda: "")()
+                raise RuntimeError(f"Telegram non-JSON response: {text[:200]}") from e
+
+        raise httpx.ConnectError(
+            f"Failed to call Telegram {method}; last_error={last_exc!r}"
+        ) from last_exc
+
+    # ------------- core send -------------
+    async def peek_thread(self, channel_key: str) -> str | None:
+        meta = self._parse(channel_key)
+        return str(meta["topic"]) if meta["topic"] is not None else ""
+
+    async def send(self, event: OutEvent) -> dict | None:
+        meta = self._parse(event.channel)
+        chat_id = meta["chat"]
+        topic_id = meta["topic"]  # None if not provided
+
+        # Streaming & upsert (editMessageText)
+        if (
+            event.type
+            in (
+                "agent.stream.start",
+                "agent.stream.delta",
+                "agent.stream.end",
+                "agent.message.update",
+            )
+            and event.upsert_key
+        ):
+            key = (event.channel, event.upsert_key)
+            if key not in self._msg_id_cache:
+                text, md = _safe_text_md(event.text or "…")
+                params = _mk_params(chat_id, topic_id, text=text, parse_mode=md)
+                resp = await self._api("sendMessage", **params)
+                msg = resp["result"]
+                self._msg_id_cache[key] = (msg["chat"]["id"], msg["message_id"])
+            else:
+                ch, mid = self._msg_id_cache[key]
+                if event.text:
+                    text, md = _safe_text_md(event.text)
+                    await self._api(
+                        "editMessageText", chat_id=ch, message_id=mid, text=text, parse_mode=md
+                    )
+            return None
+
+        # Buttons / approvals
+        if event.type in ("session.need_approval", "link.buttons"):
+            buttons = getattr(event, "buttons", None) or []
+            if not buttons:
+                opts = (event.meta or {}).get("options", ["Approve", "Reject"])
+                buttons = [
+                    type(
+                        "B", (), {"label": opts[0], "value": "approve", "style": None, "url": None}
+                    ),
+                    type(
+                        "B", (), {"label": opts[-1], "value": "reject", "style": None, "url": None}
+                    ),
+                ]
+
+            # Compact callback data: "c=<choice>|k=<resume_key>"  (<< 64 bytes)
+            resume_key = (event.meta or {}).get("resume_key") or ""
+            rows = []
+            for b in buttons[:8]:
+                label = b.label
+                val = getattr(b, "value", None) or label
+                if getattr(b, "url", None):
+                    rows.append([{"text": label, "url": b.url}])
+                else:
+                    data = f"c={str(val)[:20]}|k={resume_key}"
+                    rows.append([{"text": label, "callback_data": data}])
+
+            reply_markup = {"inline_keyboard": rows}
+            text, md = _safe_text_md(event.text or "Please approve:")
+
+            params = _mk_params(
+                chat_id, topic_id, text=text, parse_mode=md, reply_markup=reply_markup
+            )
+            resp = await self._api("sendMessage", **params)
+            msg = resp["result"]
+
+            return {
+                "correlator": Correlator(
+                    scheme="tg",
+                    channel=event.channel,
+                    thread=str(topic_id or ""),
+                    message=str(msg["message_id"]),
+                )
+            }
+
+        # File upload
+        if event.type == "file.upload" and event.file:
+            filename = event.file.get("filename", "file.bin")
+            caption = event.text or filename
+            if "bytes" in event.file:
+                files = {"document": (filename, event.file["bytes"])}
+                params = _mk_params(chat_id, topic_id, caption=caption)
+                await self._api("sendDocument", _files=files, **params)
+                return None
+            if "url" in event.file:
+                text, md = _safe_text_md(f"{caption}: {event.file['url']}")
+                params = _mk_params(chat_id, topic_id, text=text, parse_mode=md)
+                await self._api("sendMessage", **params)
+                return None
+
+        # Progress with upsert/edit (single text body)
+        if (
+            event.type in ("agent.progress.start", "agent.progress.update", "agent.progress.end")
+            and event.upsert_key
+        ):
+            r = event.rich or {}
+            title = r.get("title") or "Working..."
+            subtitle = r.get("subtitle") or ""
+            total = r.get("total")
+            cur = r.get("current") or 0
+            pct = max(0.0, min(1.0, float(cur) / float(total))) if total else 0.0
+            bar = _tg_render_bar(pct, 20)
+            pct_txt = f"{int(round(pct * 100))}%"
+            eta_txt = _tg_fmt_eta(r.get("eta_seconds"))
+            header = f"⏳ {title}"
+            if event.type == "agent.progress.end":
+                header = f"{'✅' if r.get('success', True) else '⚠️'} {title}"
+                if total:
+                    bar = _tg_render_bar(1.0, 20)
+                    pct_txt = "100%"
+
+            body_lines = [f"*{header}*"]
+            if total:
+                body_lines.append(f"`{bar}`  {pct_txt}")
+            tail = " • ".join([t for t in (subtitle, f"ETA {eta_txt}" if eta_txt else "") if t])
+            if tail:
+                body_lines.append(tail)
+            text = "\n".join(body_lines)
+
+            key = (event.channel, event.upsert_key)
+            if key not in self._msg_id_cache:
+                t, md = _safe_text_md(text)
+                params = _mk_params(chat_id, topic_id, text=t, parse_mode=md)
+                resp = await self._api("sendMessage", **params)
+                msg = resp["result"]
+                self._msg_id_cache[key] = (msg["chat"]["id"], msg["message_id"])
+            else:
+                ch, mid = self._msg_id_cache[key]
+                t, md = _safe_text_md(text)
+                await self._api(
+                    "editMessageText", chat_id=ch, message_id=mid, text=t, parse_mode=md
+                )
+            return None
+
+        # Image (sendPhoto)
+        if getattr(event, "image", None):
+            url = event.image.get("url", "")
+            caption = event.text or event.image.get("title") or ""
+            params = _mk_params(chat_id, topic_id, photo=url, caption=caption)
+            await self._api("sendPhoto", **params)
+            return None
+
+        # Default: plain message
+        t, md = _safe_text_md(event.text or "")
+        params = _mk_params(chat_id, topic_id, text=t, parse_mode=md)
+        resp = await self._api("sendMessage", **params)
+        return {
+            "correlator": Correlator(
+                scheme="tg",
+                channel=event.channel,
+                thread=str(topic_id or ""),
+                message=str(resp["result"]["message_id"]),
+            )
+        }

aethergraph/plugins/channel/adapters/webhook.py

@@ -0,0 +1,104 @@
+"""
+Webhook channel adapter.
+
+Channel key format (after alias resolution):
+  webhook:<URL>
+
+Use cases include:
+- Sending notifications to generic webhook endpoints.
+- Integrating with services like Zapier, IFTTT, Discord, etc.
+"""
+
+# aethergraph/channels/webhook.py
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import logging
+from typing import Any
+import warnings
+
+from aethergraph.contracts.services.channel import Button, ChannelAdapter, OutEvent
+from aethergraph.plugins.net.http import get_async_client
+
+logger = logging.getLogger("aethergraph.channels.webhook")
+
+
+@dataclass
+class WebhookChannelAdapter(ChannelAdapter):
+    """
+    Generic inform-only webhook adapter.
+
+    Channel key:
+      webhook:<URL>
+    Examples:
+      webhook:https://hooks.zapier.com/hooks/catch/123/abc/
+      webhook:https://discord.com/api/webhooks/.../...
+    """
+
+    default_headers: dict[str, str] | None = None
+    timeout_seconds: float = 10.0
+
+    capabilities: set[str] = frozenset({"text", "file", "rich", "buttons"})
+
+    def _url_for(self, channel_key: str) -> str:
+        try:
+            _, url = channel_key.split(":", 1)
+        except ValueError as exc:
+            raise ValueError(f"Invalid webhook channel key: {channel_key!r}") from exc
+        url = url.strip()
+        if not (url.startswith("http://") or url.startswith("https://")):
+            raise ValueError(f"Webhook channel key must contain a full URL, got: {url!r}")
+        return url
+
+    def _serialize_buttons(self, buttons: dict[str, Button] | None) -> list[dict[str, Any]]:
+        if not buttons:
+            return []
+        return [
+            {"key": k, "label": b.label, "value": b.value, "url": b.url, "style": b.style}
+            for k, b in buttons.items()
+        ]
+
+    def _serialize_file(self, file_info: dict[str, Any] | None) -> dict[str, Any] | None:
+        if not file_info:
+            return None
+        return {
+            "name": file_info.get("filename") or file_info.get("name"),
+            "mimetype": file_info.get("mimetype"),
+            "url": file_info.get("url"),
+            "size": file_info.get("size"),
+        }
+
+    def _build_payload(self, event: OutEvent) -> dict[str, Any]:
+        ts = datetime.now(timezone.utc).isoformat()
+        payload: dict[str, Any] = {
+            "type": event.type,
+            "channel": event.channel,
+            "text": event.text,
+            "meta": event.meta or {},
+            "rich": event.rich or {},
+            "buttons": self._serialize_buttons(event.buttons),
+            "file": self._serialize_file(event.file),
+            "upsert_key": event.upsert_key,
+            "timestamp": ts,
+        }
+        # For Discord-like webhooks that expect `content`
+        if event.text is not None:
+            payload["content"] = event.text
+        return payload
+
+    async def send(self, event: OutEvent) -> None:
+        url = self._url_for(event.channel)
+        payload = self._build_payload(event)
+        headers = {"Content-Type": "application/json", **(self.default_headers or {})}
+
+        try:
+            async with get_async_client(self.timeout_seconds, headers) as client:
+                resp = await client.post(url, json=payload)
+                if resp.status_code >= 400:
+                    body = resp.text
+                    logger.debug(
+                        f"[WebhookChannelAdapter] POST {url} -> HTTP {resp.status_code}. "
+                        f"Body: {body[:300]!r}"
+                    )
+        except Exception as e:
+            # Best-effort; don't bubble failures into graph control flow
+            warnings.warn(f"[WebhookChannelAdapter] Failed to POST to {url}: {e}", stacklevel=2)

aethergraph/plugins/channel/adapters/webui.py

@@ -0,0 +1,134 @@
+# src/aethergraph/plugins/channel/adapters/webui.py
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import asdict, is_dataclass
+import logging
+from typing import Any
+
+from aethergraph.contracts.services.channel import ChannelAdapter, OutEvent
+from aethergraph.services.continuations.continuation import Correlator
+
+
+class WebSessionHub:
+    def __init__(self, backlog_size: int = 100):
+        self._conns: dict[str, set] = {}
+        self._backlog: dict[str, deque[dict]] = {}
+        self._backlog_size = backlog_size
+
+    async def attach(self, session_id: str, sender):
+        self._conns.setdefault(session_id, set()).add(sender)
+        # flush backlog to this new connection
+        for payload in list(self._backlog.get(session_id, [])):
+            try:
+                await sender(payload)
+            except Exception:
+                logger = logging.getLogger("aethergraph.plugins.channel.adapters.webui")
+                logger.warning(f"Failed to flush backlog payload to session {session_id}")
+
+    async def detach(self, session_id: str, sender):
+        s = self._conns.get(session_id)
+        if s and sender in s:
+            s.remove(sender)
+            if not s:
+                self._conns.pop(session_id, None)
+
+    async def emit(self, session_id: str, payload: dict):
+        conns = list(self._conns.get(session_id, []))
+        if conns:
+            for send in conns:
+                try:
+                    await send(payload)
+                except Exception:
+                    await self.detach(session_id, send)
+            return
+
+        # no live connections → store to backlog
+        q = self._backlog.setdefault(session_id, deque(maxlen=self._backlog_size))
+        q.append(payload)
+
+
+def _serialize_event(event: OutEvent) -> dict:
+    """Dataclass → dict; normalize buttons; strip file bytes; drop None."""
+    if is_dataclass(event):
+        payload = asdict(event)
+    else:
+        # be lenient if a pydantic-like instance sneaks in
+        payload = (
+            (getattr(event, "model_dump", None) and event.model_dump())
+            or (getattr(event, "dict", None) and event.dict())
+            or dict(event)
+        )
+
+    # normalize buttons dict -> list
+    btns = payload.get("buttons")
+    if isinstance(btns, dict):
+        payload["buttons"] = list(btns.values())
+
+    # drop binary bytes from file
+    f = payload.get("file")
+    if isinstance(f, dict) and "bytes" in f:
+        f = f.copy()
+        f.pop("bytes", None)
+        payload["file"] = f
+
+    # clean None
+    return {k: v for k, v in payload.items() if v is not None}
+
+
+class WebChannelAdapter(ChannelAdapter):
+    """
+    Channel key: 'web:session/{session_id}'
+    Mirrors Slack adapter semantics for:
+      - correlators
+      - stream/progress upserts via upsert_key
+      - buttons/image/file payload shapes
+    """
+
+    capabilities: set[str] = {"text", "buttons", "image", "file", "edit", "stream"}
+
+    def __init__(self, hub: WebSessionHub):
+        self.hub = hub
+        self._first_msg_by_key: dict[
+            tuple[str, str], str
+        ] = {}  # (channel, upsert_key) -> synthetic message id
+        self._seq_by_chan: dict[str, int] = {}
+
+    @staticmethod
+    def _parse(channel_key: str) -> dict:
+        # "web:session/{id}" -> {"session": "..."}
+        parts = channel_key.split(":", 1)[1]  # session/{id}
+        k, v = parts.split("/", 1)
+        return {k: v}
+
+    def _next_seq(self, ch: str) -> str:
+        n = self._seq_by_chan.get(ch, 0) + 1
+        self._seq_by_chan[ch] = n
+        return str(n)
+
+    async def peek_thread(self, channel_key: str) -> str | None:
+        # no threads in web adapter
+        return None
+
+    async def send(self, event: OutEvent) -> dict | None:
+        meta = self._parse(event.channel)
+        session_id = meta["session"]
+
+        # upsert bookkeeping like Slack: ensure a stable logical message per upsert_key
+        if event.upsert_key:
+            key = (event.channel, event.upsert_key)
+            if key not in self._first_msg_by_key:
+                self._first_msg_by_key[key] = self._next_seq(event.channel)
+
+        payload: dict[str, Any] = _serialize_event(event)
+        await self.hub.emit(session_id, payload)
+
+        # return correlator so ChannelSession can bind (consistent with Slack)
+        return {
+            "correlator": Correlator(
+                scheme="web",
+                channel=event.channel,
+                thread=None,
+                message=self._next_seq(event.channel),
+            )
+        }

aethergraph/plugins/channel/routes/console_routes.py

@@ -0,0 +1,86 @@
+from fastapi import APIRouter, Query, Request
+from pydantic import BaseModel
+
+from aethergraph.services.continuations.continuation import Correlator
+
+router = APIRouter()
+
+
+@router.get("/api/continuations/latest")
+async def latest(request: Request, channel: str, kind: str | None = Query(None)):
+    """
+    Console: resolve newest open continuation bound to this channel.
+    We use a channel-wide correlator (no thread/message).
+    TODO:  add a 'message' query param later if want more precise matching.
+    """
+    c = request.app.state.container
+
+    # First try channel-wide correlator (message="")
+    corr = Correlator(scheme="console", channel=channel, thread="", message="")
+    cont = await c.cont_store.find_by_correlator(corr=corr)
+
+    # (Optional) If we pass ?message=... from a UI client, try that first:
+    # message = request.query_params.get("message")
+    # if message:
+    #     corr_precise = Correlator(scheme="console", channel=channel, thread="", message=message)
+    #     cont = c.cont_store.find_by_correlator(corr=corr_precise) or cont
+
+    if kind and cont and cont.kind != kind:
+        # If caller asks for a specific kind, and the found one doesn't match, return None
+        return None
+
+    return cont.to_dict() if cont else None
+
+
+class ConsoleResume(BaseModel):
+    run_id: str
+    node_id: str
+    token: str
+    payload: dict
+
+
+@router.post("/api/console/resume")
+async def console_resume(request: Request, req: ConsoleResume):
+    c = request.app.state.container
+    payload = dict(req.payload or {})
+    cont = (
+        await c.cont_store.get_by_token(req.token)
+        if hasattr(c.cont_store, "get_by_token")
+        else None
+    )
+
+    if cont and getattr(cont, "kind", "") == "approval":
+        # If client already parsed the choice, don't override it
+        if "choice" in payload or "approved" in payload:
+            pass  # trust the client (console watcher)
+        else:
+            raw = str(payload.get("text", "")).strip()
+            # Try to use mappings echoed by the client (if any)
+            options_map = payload.get("options_map") or {}
+            label_map = payload.get("options_label_to_value") or {}
+
+            # Otherwise reconstruct from the Continuation.prompt
+            if not options_map and isinstance(cont.prompt, dict):
+                labels = cont.prompt.get("buttons") or cont.prompt.get("options") or []
+                options_map = {
+                    str(i + 1): str(lbl).lower() for i, lbl in enumerate(labels, start=1)
+                }
+                label_map = {str(lbl).lower(): str(lbl).lower() for lbl in labels}
+
+            if raw.isdigit() and raw in options_map:
+                choice = options_map[raw]
+            else:
+                choice = label_map.get(raw.lower(), raw.lower())
+
+            payload = {
+                "approved": choice in {"approve", "approved", "yes", "y"},
+                "choice": choice,
+            }
+
+    await c.resume_router.resume(req.run_id, req.node_id, req.token, payload)
+
+    # TODO: (optional safety) if our resume router does NOT mark it closed internally:
+    # c.cont_store.mark_closed(req.token) or delete it;
+    # now it seems we haven't gone through resume_router for console resumes yet. So the continuation remains open.
+
+    return {"ok": True}

aethergraph/plugins/channel/routes/slack_routes.py

@@ -0,0 +1,49 @@
+# slack_http_routes.py
+
+import json
+
+from fastapi import APIRouter, Request
+from starlette.responses import JSONResponse
+
+from ..utils.slack_utils import (
+    _verify_sig,
+    handle_slack_events_common,
+    handle_slack_interactive_common,
+)
+
+router = APIRouter()
+
+
+@router.post("/slack/events")
+async def slack_events(request: Request):
+    settings = request.app.state.settings
+    container = request.app.state.container
+
+    body = await request.body()
+    _verify_sig(request, body)  # HTTP-only
+
+    payload = json.loads(body)
+
+    # URL verification (Events API handshake)
+    if payload.get("type") == "url_verification":
+        # Just echo the challenge back
+        return JSONResponse(payload)
+
+    # Delegate real work to shared handler
+    resp = await handle_slack_events_common(container, settings, payload)
+    return JSONResponse(resp or {})
+
+
+@router.post("/slack/interact")
+async def slack_interact(request: Request):
+    """Handle interactive components (buttons) from Slack via HTTP."""
+    container = request.app.state.container
+
+    body = await request.body()
+    _verify_sig(request, body)  # HTTP-only
+
+    form = await request.form()
+    payload = json.loads(form["payload"])
+
+    await handle_slack_interactive_common(container, payload)
+    return JSONResponse({})  # ack