pboy 0.1.0__py3-none-any.whl

pboy/__init__.py

@@ -0,0 +1,25 @@
+# Pageboy (`pboy` / `pb`)
+"""
+pboy — Zero-Ops Agent Event Orchestrator & Dispatcher
+
+Slack, Telegram, Jira, Confluence 의 멀티 채널 이벤트를 로컬 머신에서 수신하고,
+이벤트 구동 방식으로 에이전트 하네스 (Harness) 를 실행·동기화하는 도구입니다.
+
+사용법:
+    uvx pboy daemon --ui                  # 데몬 + 웹 UI 시작
+    pboy hook register --name ... --exec ...  # 훅 등록
+    pboy state put --event-id ... --status running  # 하네스 내부 상태 보고
+    pboy event complete --event-id ... --summary ...  # 완료 처리
+
+패키지 구조:
+    cli/       — CLI 명령어 (hook, state, event, daemon, ui)
+    core/      — EventNormalizer, HookRouter, LeaseEngine
+    channels/  — Telegram, Slack, Jira/Confluence 수신부
+    store/     — SQLite AES 암호화 저장소
+    harness/   — Subprocess executor (fork/exec)
+    ui/        — 임베디드 로컬 웹 대시보드
+    models/    — CloudEvents v1.0 호환 도메인 모델
+"""
+
+__version__ = "0.1.0"
+__author__ = "fritzprix"

pboy/channels/README.md

@@ -0,0 +1,128 @@
+# Channels — `pboy.channels`
+
+Inbound **wake-up** receivers. Adapters push **raw** payloads into `Engine.process_event`
+(normalization stays in `pboy.core.normalizer`).
+
+Ticketing systems (Jira / Confluence) are **not** required ChannelAdapters: agents
+call their REST APIs from the harness. See [`docs/architecture-channels.md`](../../../docs/architecture-channels.md).
+
+## Module layout
+
+| File | Role |
+|------|------|
+| `base.py` | `ChannelAdapter` / `EventEmitter` protocols |
+| `registry.py` | Enable/start/stop via `PB_CHANNELS_ENABLED` |
+| `fake.py` | In-process fake adapter (tests / demos) |
+| `telegram.py` | Bot API long-poll (`getUpdates`) |
+| `slack.py` | Socket Mode (Events API over WebSocket) |
+
+## Enable channels
+
+**Preferred (persisted store + CLI):**
+
+```bash
+pboy channel set-secret telegram --value '123456:ABC...'
+pboy channel enable telegram
+pboy channel list
+# • telegram [enabled, stopped, secret=yes]   # until daemon starts it
+
+export PB_AUTH_TOKEN=dev-secret
+pboy daemon --host 127.0.0.1 --port 8080
+# /healthz → channels.running includes "telegram"
+```
+
+With `PB_DAEMON_URL` set, the same `pboy channel …` commands hit the daemon HTTP API
+(and can start/stop adapters live).
+
+**Env override** (wins over store when the variable is set, including empty):
+
+```bash
+export PB_CHANNELS_ENABLED=telegram
+export PB_TELEGRAM_BOT_TOKEN='123456:ABC...'
+```
+
+## Telegram setup (BotFather)
+
+1. In Telegram, talk to [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token.
+2. Store the token and enable the channel:
+
+```bash
+pboy channel set-secret telegram --value '<token from BotFather>'
+pboy channel enable telegram
+```
+
+Or use env: `PB_TELEGRAM_BOT_TOKEN` (overrides store when set).
+
+3. Start the daemon (same DB as the CLI):
+
+```bash
+export PB_AUTH_TOKEN=dev-secret
+pboy daemon --host 127.0.0.1 --port 8080
+```
+
+4. Register a hook for `telegram:message`, then message the bot:
+
+```bash
+export PB_DAEMON_URL=http://127.0.0.1:8080
+pboy hook register \
+  --name tg-echo \
+  --topic 'telegram:message' \
+  --exec 'echo hello-from-tg' \
+  --timeout 30
+pboy channel list
+```
+
+Long-poll calls `deleteWebhook` on start so it does not fight a webhook subscription.
+On API errors the poller backs off exponentially (1s → 60s).
+
+## Outbound sync (completion reply)
+
+When a harness finishes work it can close the loop:
+
+```bash
+pboy event complete "$PB_EVENT_ID" \
+  --summary 'Restarted worker-2' \
+  --sync telegram
+```
+
+This uses the same bot token, posts to `event.data.channel_id`, and replies to
+`event.data.entity_key` (message id) when numeric. Failed sync exits CLI non-zero
+but the completion record is still persisted. Re-running
+`pboy event complete … --sync telegram` retries **failed/missing** sync targets
+only (successful ones are not re-sent; original summary is kept).
+
+## Adapter contract
+
+```python
+class ChannelAdapter(Protocol):
+    @property
+    def name(self) -> str: ...
+    async def start(self) -> None: ...
+    async def stop(self) -> None: ...
+```
+
+## Transports
+
+| Channel | Transport | Tunnel | Role |
+|---------|-----------|--------|------|
+| Telegram | Long-poll `getUpdates` | No | Wake-up ✅ |
+| Slack | Socket Mode | No | Wake-up ✅ |
+| Jira / Confluence | **Agent REST** (GET/POST) | No | Work surface — not a ChannelAdapter |
+| Jira webhook + relay | Push HTTPS | Public URL | Deferred / optional only |
+
+## Slack setup (Socket Mode)
+
+1. Create a Slack app with **Socket Mode** enabled; generate an **App-level token**
+   (`xapp-…`) with `connections:write`, and a **Bot token** (`xoxb-…`) with
+   `chat:write` + event subscriptions for `message.channels` / `message.im` as needed.
+2. Store secrets (both required):
+
+```bash
+pboy channel set-secret slack --secret-name bot_token --value 'xoxb-...'
+pboy channel set-secret slack --secret-name app_token --value 'xapp-...'
+pboy channel enable slack
+```
+
+Or env: `PB_SLACK_BOT_TOKEN` + `PB_SLACK_APP_TOKEN`.
+
+3. Start daemon, register a hook on `slack:message`, then message the app.

pboy/channels/__init__.py

@@ -0,0 +1,16 @@
+"""Inbound channel adapters (Telegram, Slack, …)."""
+
+from __future__ import annotations
+
+from pboy.channels.base import ChannelAdapter, EventEmitter
+from pboy.channels.registry import ChannelRegistry
+from pboy.channels.slack import SlackChannel
+from pboy.channels.telegram import TelegramChannel
+
+__all__ = [
+    "ChannelAdapter",
+    "ChannelRegistry",
+    "EventEmitter",
+    "SlackChannel",
+    "TelegramChannel",
+]

pboy/channels/base.py

@@ -0,0 +1,46 @@
+"""Channel adapter protocol — inbound platforms push raw events into the Engine."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+def redact_secret(message: str, secret: str | None) -> str:
+    """Replace a secret substring in log/error text when present."""
+    if secret:
+        return message.replace(secret, "[REDACTED]")
+    return message
+
+
+@runtime_checkable
+class EventEmitter(Protocol):
+    """Sink used by adapters to hand raw platform payloads to the Engine."""
+
+    async def __call__(
+        self,
+        raw_payload: dict[str, Any],
+        source: str,
+        *,
+        dispatch: bool = True,
+    ) -> Any: ...
+
+
+@runtime_checkable
+class ChannelAdapter(Protocol):
+    """Long-running inbound receiver (poll/socket/webhook consumer)."""
+
+    @property
+    def name(self) -> str:
+        """Stable adapter id (e.g. ``telegram``, ``fake``)."""
+        ...
+
+    async def start(self) -> None:
+        """Begin receiving (idempotent preferred)."""
+        ...
+
+    async def stop(self) -> None:
+        """Stop receiving and release resources (idempotent preferred)."""
+        ...
+
+
+__all__ = ["ChannelAdapter", "EventEmitter", "redact_secret"]

pboy/channels/config.py

@@ -0,0 +1,103 @@
+"""Persisted channel enablement and per-channel secret key names."""
+
+from __future__ import annotations
+
+import os
+
+from pboy.store.base import StoreBase
+
+CHANNELS_ENABLED_SECRET = "channels.enabled"
+
+# channel name → required encrypted store secret keys
+CHANNEL_SECRET_KEYS: dict[str, tuple[str, ...]] = {
+    "telegram": ("telegram.bot_token",),
+    "slack": ("slack.bot_token", "slack.app_token"),
+}
+
+
+def parse_enabled_names(raw: str | None) -> list[str]:
+    """Parse a comma-separated enable list into unique lowercase names."""
+    if not raw:
+        return []
+    names: list[str] = []
+    seen: set[str] = set()
+    for part in raw.split(","):
+        name = part.strip().lower()
+        if not name or name in seen:
+            continue
+        seen.add(name)
+        names.append(name)
+    return names
+
+
+def format_enabled_names(names: list[str]) -> str:
+    return ",".join(parse_enabled_names(",".join(names)))
+
+
+def env_channels_enabled_override() -> str | None:
+    """Return raw ``PB_CHANNELS_ENABLED`` when the env var is set (including empty)."""
+    if "PB_CHANNELS_ENABLED" in os.environ:
+        return os.environ["PB_CHANNELS_ENABLED"]
+    return None
+
+
+async def load_enabled_from_store(store: StoreBase) -> list[str]:
+    raw = await store.get_secret(CHANNELS_ENABLED_SECRET)
+    return parse_enabled_names(raw)
+
+
+async def save_enabled_to_store(store: StoreBase, names: list[str]) -> None:
+    await store.put_secret(CHANNELS_ENABLED_SECRET, format_enabled_names(names))
+
+
+def secret_keys_for_channel(name: str) -> tuple[str, ...]:
+    return CHANNEL_SECRET_KEYS.get(name.strip().lower(), ())
+
+
+def resolve_secret_key(channel: str, secret_name: str | None = None) -> str:
+    """Resolve store key for ``pboy channel set-secret``.
+
+    Single-secret channels (telegram) omit ``secret_name``.
+    Multi-secret channels (slack) require ``bot_token`` / ``app_token`` (or full key).
+    """
+    key = channel.strip().lower()
+    keys = CHANNEL_SECRET_KEYS.get(key)
+    if not keys:
+        raise ValueError(
+            f"Channel '{key}' has no secret mapping. Supported: {', '.join(sorted(CHANNEL_SECRET_KEYS))}"
+        )
+    if secret_name and secret_name.strip():
+        sn = secret_name.strip().lower()
+        full = sn if "." in sn else f"{key}.{sn}"
+        if full not in keys:
+            short = ", ".join(k.split(".", 1)[-1] for k in keys)
+            raise ValueError(f"Unknown secret '{secret_name}' for '{key}'. Use one of: {short}")
+        return full
+    if len(keys) == 1:
+        return keys[0]
+    short = ", ".join(k.split(".", 1)[-1] for k in keys)
+    raise ValueError(f"Channel '{key}' requires --secret-name ({short})")
+
+
+def secret_key_for_channel(name: str) -> str | None:
+    """Backward-compatible: primary secret key, or None if multi-secret without default."""
+    keys = secret_keys_for_channel(name)
+    if not keys:
+        return None
+    if len(keys) == 1:
+        return keys[0]
+    return None
+
+
+__all__ = [
+    "CHANNELS_ENABLED_SECRET",
+    "CHANNEL_SECRET_KEYS",
+    "env_channels_enabled_override",
+    "format_enabled_names",
+    "load_enabled_from_store",
+    "parse_enabled_names",
+    "resolve_secret_key",
+    "save_enabled_to_store",
+    "secret_key_for_channel",
+    "secret_keys_for_channel",
+]

pboy/channels/fake.py

@@ -0,0 +1,58 @@
+"""In-process fake channel for tests and local demos (no network)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+from pboy.channels.base import EventEmitter
+
+
+class FakeChannel:
+    """Test/demo adapter: ``push`` injects a raw payload through the Engine sink."""
+
+    def __init__(
+        self,
+        emit: EventEmitter,
+        *,
+        source: str = "jira",
+        name: str = "fake",
+    ) -> None:
+        self._emit = emit
+        self._source = source
+        self._name = name
+        self._started = False
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def source(self) -> str:
+        return self._source
+
+    @property
+    def started(self) -> bool:
+        return self._started
+
+    async def start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        logger.info("channel.connect name={} source={}", self._name, self._source)
+
+    async def stop(self) -> None:
+        if not self._started:
+            return
+        self._started = False
+        logger.info("channel.disconnect name={} source={}", self._name, self._source)
+
+    async def push(self, payload: dict[str, Any], *, dispatch: bool = True) -> Any:
+        """Emit a raw platform payload into the Engine (adapter must be started)."""
+        if not self._started:
+            raise RuntimeError(f"Channel '{self._name}' is not started")
+        return await self._emit(payload, self._source, dispatch=dispatch)
+
+
+__all__ = ["FakeChannel"]

pboy/channels/registry.py

@@ -0,0 +1,230 @@
+"""Load and lifecycle-manage enabled channel adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from loguru import logger
+
+from pboy.channels.base import ChannelAdapter, EventEmitter
+from pboy.channels.config import (
+    env_channels_enabled_override,
+    load_enabled_from_store,
+    parse_enabled_names,
+    resolve_secret_key,
+    save_enabled_to_store,
+    secret_keys_for_channel,
+)
+from pboy.channels.fake import FakeChannel
+from pboy.channels.slack import build_slack_channel
+from pboy.channels.telegram import build_telegram_channel
+from pboy.core.config import Settings, get_settings
+from pboy.store.base import StoreBase
+
+AdapterFactory = Callable[[EventEmitter, StoreBase, Settings], ChannelAdapter | None]
+
+
+def _fake_factory(emit: EventEmitter, store: StoreBase, settings: Settings) -> ChannelAdapter:
+    del store, settings
+    return FakeChannel(emit)
+
+
+BUILTIN_FACTORIES: dict[str, AdapterFactory] = {
+    "fake": _fake_factory,
+    "telegram": build_telegram_channel,
+    "slack": build_slack_channel,
+}
+
+
+class ChannelRegistry:
+    """Register adapters and start only those enabled via env or store."""
+
+    def __init__(
+        self,
+        emit: EventEmitter,
+        store: StoreBase,
+        *,
+        settings: Settings | None = None,
+        factories: dict[str, AdapterFactory] | None = None,
+    ) -> None:
+        self._emit = emit
+        self._store = store
+        self._settings = settings or get_settings()
+        self._factories = dict(BUILTIN_FACTORIES if factories is None else factories)
+        self._instances: dict[str, ChannelAdapter] = {}
+        self._running: list[str] = []
+
+    @property
+    def running(self) -> list[str]:
+        return list(self._running)
+
+    def known_names(self) -> list[str]:
+        return sorted(self._factories.keys() | self._instances.keys())
+
+    def register_factory(self, name: str, factory: AdapterFactory) -> None:
+        """Register or replace a factory under a lowercase channel name."""
+        self._factories[name.strip().lower()] = factory
+
+    def register(self, adapter: ChannelAdapter) -> None:
+        """Register a pre-built adapter instance (tests / custom wiring)."""
+        self._instances[adapter.name.strip().lower()] = adapter
+
+    def get(self, name: str) -> ChannelAdapter | None:
+        return self._instances.get(name.strip().lower())
+
+    async def resolve_enabled_names(self) -> list[str]:
+        """Env ``PB_CHANNELS_ENABLED`` overrides store when the variable is set."""
+        override = env_channels_enabled_override()
+        if override is not None:
+            return parse_enabled_names(override)
+        return await load_enabled_from_store(self._store)
+
+    def _resolve(self, name: str) -> ChannelAdapter | None:
+        key = name.strip().lower()
+        if key in self._instances:
+            return self._instances[key]
+        factory = self._factories.get(key)
+        if factory is None:
+            logger.warning("channel.unknown name={} — skipping", key)
+            return None
+        adapter = factory(self._emit, self._store, self._settings)
+        if adapter is None:
+            logger.warning("channel.unavailable name={} — factory returned None", key)
+            return None
+        self._instances[key] = adapter
+        return adapter
+
+    async def start_enabled(self) -> None:
+        """Start adapters listed as enabled; leave others untouched."""
+        enabled = await self.resolve_enabled_names()
+        if not enabled:
+            logger.info("channel.registry no channels enabled")
+            return
+
+        for name in enabled:
+            await self._start_one(name)
+
+    async def _start_one(self, name: str) -> None:
+        key = name.strip().lower()
+        if key in self._running:
+            return
+        adapter = self._resolve(key)
+        if adapter is None:
+            return
+        await adapter.start()
+        self._running.append(key)
+        logger.info("channel.started name={}", key)
+
+    async def stop_all(self) -> None:
+        """Stop every adapter that was started by this registry."""
+        for name in reversed(self._running):
+            adapter = self._instances.get(name)
+            if adapter is None:
+                continue
+            try:
+                await adapter.stop()
+                logger.info("channel.stopped name={}", name)
+            except Exception:
+                logger.exception("channel.stop_failed name={}", name)
+        self._running.clear()
+
+    async def enable(self, name: str) -> None:
+        """Persist enablement and start the adapter if not already running."""
+        key = name.strip().lower()
+        if key not in self._factories and key not in self._instances:
+            raise ValueError(f"Unknown channel '{key}'. Known: {', '.join(self.known_names())}")
+        enabled = await self.resolve_enabled_names()
+        if key not in enabled:
+            enabled.append(key)
+            if env_channels_enabled_override() is None:
+                await save_enabled_to_store(self._store, enabled)
+            else:
+                logger.warning(
+                    "channel.enable name={} — PB_CHANNELS_ENABLED is set; "
+                    "store not updated (restart with env or unset override)",
+                    key,
+                )
+        await self._start_one(key)
+
+    async def disable(self, name: str) -> None:
+        """Persist disablement and stop the adapter if running."""
+        key = name.strip().lower()
+        enabled = [n for n in await self.resolve_enabled_names() if n != key]
+        if env_channels_enabled_override() is None:
+            await save_enabled_to_store(self._store, enabled)
+        else:
+            logger.warning(
+                "channel.disable name={} — PB_CHANNELS_ENABLED is set; store not updated",
+                key,
+            )
+        if key in self._running:
+            adapter = self._instances.get(key)
+            if adapter is not None:
+                await adapter.stop()
+            self._running = [n for n in self._running if n != key]
+            logger.info("channel.stopped name={}", key)
+
+    def env_covers_secret(self, secret_key: str) -> bool:
+        """True when the matching ``PB_*`` env already supplies this secret."""
+        if secret_key == "telegram.bot_token":
+            return bool(self._settings.telegram_bot_token.strip())
+        if secret_key == "slack.bot_token":
+            return bool(self._settings.slack_bot_token.strip())
+        if secret_key == "slack.app_token":
+            return bool(self._settings.slack_app_token.strip())
+        return False
+
+    async def set_channel_secret(
+        self,
+        name: str,
+        value: str,
+        *,
+        secret_name: str | None = None,
+    ) -> str:
+        """Store the channel token/secret; returns the secret key used."""
+        if not value.strip():
+            raise ValueError("Secret value must not be empty")
+        secret_key = resolve_secret_key(name, secret_name)
+        await self._store.put_secret(secret_key, value.strip())
+        return secret_key
+
+    async def list_status(self) -> list[dict[str, Any]]:
+        enabled = set(await self.resolve_enabled_names())
+        running = set(self._running)
+        rows: list[dict[str, Any]] = []
+        for name in self.known_names():
+            keys = secret_keys_for_channel(name)
+            has_secret = True
+            if keys:
+                for sk in keys:
+                    if self.env_covers_secret(sk):
+                        continue
+                    if (await self._store.get_secret(sk)) is None:
+                        has_secret = False
+                        break
+            else:
+                has_secret = False
+            rows.append(
+                {
+                    "name": name,
+                    "enabled": name in enabled,
+                    "running": name in running,
+                    "secret_key": keys[0] if len(keys) == 1 else None,
+                    "secret_keys": list(keys),
+                    "has_secret": has_secret if keys else False,
+                }
+            )
+        return rows
+
+    async def status(self) -> dict[str, Any]:
+        """Compact status for /healthz."""
+        return {
+            "enabled": await self.resolve_enabled_names(),
+            "running": self.running,
+            "known": self.known_names(),
+            "env_override": env_channels_enabled_override() is not None,
+        }
+
+
+__all__ = ["BUILTIN_FACTORIES", "AdapterFactory", "ChannelRegistry"]