byte-bot 0.1.0__tar.gz

byte_bot-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+build/
+*.egg-info/

byte_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MD Raqibul Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

byte_bot-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: byte-bot
+Version: 0.1.0
+Summary: Local dashboard for monitoring coding agents with optional Telegram status
+Project-URL: Homepage, https://github.com/erajtob/byte-bot
+Project-URL: Source, https://github.com/erajtob/byte-bot
+Project-URL: Issues, https://github.com/erajtob/byte-bot/issues
+Project-URL: Security, https://github.com/erajtob/byte-bot/security
+Author-email: MD Raqibul Islam <hello@eraj.dev>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: textual<9,>=8.2.8
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/byte-wordmark.svg" alt="byte-bot wordmark" width="760">
+</p>
+
+# byte-bot
+
+**See what your coding agents are doing — and know when they need you.**
+
+Byte is a small, local dashboard for coding agents. It watches supported agents
+without controlling them, gives you one terminal view, and can optionally send the same
+status to a private Telegram chat.
+
+<p align="center">
+  <img src="docs/assets/dashboard-demo.svg" alt="Synthetic byte-bot dashboard activity demo" width="1000">
+</p>
+
+*The dashboard above uses synthetic demo data.*
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/erajtob/byte-bot/main/install.sh | sh
+```
+
+## Run
+
+```bash
+byte-bot
+```
+
+On first launch, choose the demo or follow the guided setup for your machine.
+
+Already installed?
+
+```bash
+byte-bot update
+```
+
+**Beta status:** Linux-first. macOS has a foreground path but is not Beta-verified yet;
+Windows is not Beta-supported yet.
+
+## What you can see
+
+- active supported agent sessions, grouped by project when Byte can prove the workspace;
+- a short current-activity line such as reading files, editing, running a command, or thinking;
+- model and usage information when the source provides it;
+- permission or input blockers that need you;
+- whether status is fresh or stale, and when a source could not be read.
+
+Byte does not store or display private chain-of-thought, prompt bodies, command output,
+or raw tool arguments as status.
+
+## Telegram (optional)
+
+<p align="center">
+  <img src="docs/assets/telegram-preview.svg" alt="Synthetic byte-bot Telegram preview" width="760">
+</p>
+
+Pair Byte with one private Telegram chat to check status away from the terminal and receive
+quiet notifications when an agent needs attention.
+
+Telegram does **not** become a shell. It cannot change configured commands, start agents,
+control Docker or sudo, browse the filesystem, or turn chat text into command input.
+
+## Supported today
+
+| Source | What Byte currently supports |
+| --- | --- |
+| OpenCode | Active sessions, projects, model/usage, current activity, and permission/input waits |
+| Codex CLI 0.155.1 | Passive observation of an existing `exec --json` capture |
+| Structured project sources | Status and events provided by a project adapter |
+| Local status commands | Exact read-only commands you configure, with timeouts |
+
+OpenCode is not pinned to one release number. Byte checks the small set of data it
+relies on; if that data becomes incompatible, Byte marks the source degraded instead
+of guessing.
+
+## Read-only by design
+
+byte-bot v0.1 only observes:
+
+- Telegram cannot run arbitrary commands or control your agents;
+- Byte only runs the exact local status commands you configure, with timeouts;
+- there is no hosted Byte account; optional Telegram uses outbound connections only.
+
+For the technical details, read [Security](SECURITY.md),
+[How it works](docs/how-it-works.md), and [Compatibility](docs/compatibility.md).
+
+## More
+
+- [Install, update, and remove](docs/install.md)
+- [Setup and configuration](docs/install.md#first-launch)
+- [Support and troubleshooting](docs/support.md)
+- [How it works](docs/how-it-works.md)
+- [Contributing](CONTRIBUTING.md)
+
+byte-bot stays project-agnostic and does not require any particular workload.
+
+## License
+
+[MIT](LICENSE).

byte_bot-0.1.0/README.md

@@ -0,0 +1,101 @@
+<p align="center">
+  <img src="docs/assets/byte-wordmark.svg" alt="byte-bot wordmark" width="760">
+</p>
+
+# byte-bot
+
+**See what your coding agents are doing — and know when they need you.**
+
+Byte is a small, local dashboard for coding agents. It watches supported agents
+without controlling them, gives you one terminal view, and can optionally send the same
+status to a private Telegram chat.
+
+<p align="center">
+  <img src="docs/assets/dashboard-demo.svg" alt="Synthetic byte-bot dashboard activity demo" width="1000">
+</p>
+
+*The dashboard above uses synthetic demo data.*
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/erajtob/byte-bot/main/install.sh | sh
+```
+
+## Run
+
+```bash
+byte-bot
+```
+
+On first launch, choose the demo or follow the guided setup for your machine.
+
+Already installed?
+
+```bash
+byte-bot update
+```
+
+**Beta status:** Linux-first. macOS has a foreground path but is not Beta-verified yet;
+Windows is not Beta-supported yet.
+
+## What you can see
+
+- active supported agent sessions, grouped by project when Byte can prove the workspace;
+- a short current-activity line such as reading files, editing, running a command, or thinking;
+- model and usage information when the source provides it;
+- permission or input blockers that need you;
+- whether status is fresh or stale, and when a source could not be read.
+
+Byte does not store or display private chain-of-thought, prompt bodies, command output,
+or raw tool arguments as status.
+
+## Telegram (optional)
+
+<p align="center">
+  <img src="docs/assets/telegram-preview.svg" alt="Synthetic byte-bot Telegram preview" width="760">
+</p>
+
+Pair Byte with one private Telegram chat to check status away from the terminal and receive
+quiet notifications when an agent needs attention.
+
+Telegram does **not** become a shell. It cannot change configured commands, start agents,
+control Docker or sudo, browse the filesystem, or turn chat text into command input.
+
+## Supported today
+
+| Source | What Byte currently supports |
+| --- | --- |
+| OpenCode | Active sessions, projects, model/usage, current activity, and permission/input waits |
+| Codex CLI 0.155.1 | Passive observation of an existing `exec --json` capture |
+| Structured project sources | Status and events provided by a project adapter |
+| Local status commands | Exact read-only commands you configure, with timeouts |
+
+OpenCode is not pinned to one release number. Byte checks the small set of data it
+relies on; if that data becomes incompatible, Byte marks the source degraded instead
+of guessing.
+
+## Read-only by design
+
+byte-bot v0.1 only observes:
+
+- Telegram cannot run arbitrary commands or control your agents;
+- Byte only runs the exact local status commands you configure, with timeouts;
+- there is no hosted Byte account; optional Telegram uses outbound connections only.
+
+For the technical details, read [Security](SECURITY.md),
+[How it works](docs/how-it-works.md), and [Compatibility](docs/compatibility.md).
+
+## More
+
+- [Install, update, and remove](docs/install.md)
+- [Setup and configuration](docs/install.md#first-launch)
+- [Support and troubleshooting](docs/support.md)
+- [How it works](docs/how-it-works.md)
+- [Contributing](CONTRIBUTING.md)
+
+byte-bot stays project-agnostic and does not require any particular workload.
+
+## License
+
+[MIT](LICENSE).

byte_bot-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "byte-bot"
+version = "0.1.0"
+description = "Local dashboard for monitoring coding agents with optional Telegram status"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+authors = [{name = "MD Raqibul Islam", email = "hello@eraj.dev"}]
+dependencies = [
+    "textual>=8.2.8,<9",
+]
+
+[project.urls]
+Homepage = "https://github.com/erajtob/byte-bot"
+Source = "https://github.com/erajtob/byte-bot"
+Issues = "https://github.com/erajtob/byte-bot/issues"
+Security = "https://github.com/erajtob/byte-bot/security"
+
+[project.scripts]
+byte-bot = "byte_bot.cli:main"
+
+[dependency-groups]
+dev = ["ruff>=0.13,<1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/byte_bot"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/byte_bot", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

byte_bot-0.1.0/src/byte_bot/__init__.py

@@ -0,0 +1,3 @@
+"""byte-bot."""
+
+__version__ = "0.1.0"

byte_bot-0.1.0/src/byte_bot/__main__.py

@@ -0,0 +1,3 @@
+from byte_bot.cli import main
+
+raise SystemExit(main())

byte_bot-0.1.0/src/byte_bot/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Static reviewed adapter-name registry.
+
+Importing the package must not eagerly import adapter implementations: config and
+legacy adapters depend on each other at module-load time. Runtime code imports the
+specific reviewed implementation it needs.
+"""
+
+from __future__ import annotations
+
+ADAPTER_NAMES: tuple[str, ...] = (
+    "codex-exec-jsonl",
+    "legacy-command",
+    "opencode-http",
+)
+
+__all__ = ["ADAPTER_NAMES"]

byte_bot-0.1.0/src/byte_bot/adapters/codex_exec_jsonl.py

@@ -0,0 +1,325 @@
+"""Version-pinned passive Codex exec JSONL observation.
+
+The adapter reads one explicitly configured existing capture. It never invokes
+Codex, resumes a thread, attaches to a session, or retains transcript/tool bodies.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import stat as stat_module
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from byte_bot.model import (
+    CollectionError,
+    Evidence,
+    Lifecycle,
+    Session,
+    SourceHealth,
+    SourceStatus,
+)
+
+ADAPTER_NAME = "codex-exec-jsonl"
+SUPPORTED_VERSION = "0.155.1"
+FIELD_VERSION = "codex-0.155.1-exec-jsonl"
+CAPABILITIES = ("sessions", "source-health")
+MAX_CAPTURE_BYTES = 64 * 1024
+MAX_RECORDS = 32
+MAX_THREAD_ID_LEN = 128
+
+_IGNORED_ITEM_TYPES = frozenset({"item.started", "item.updated", "item.completed"})
+_ALLOWED_TYPES = frozenset(
+    {
+        "thread.started",
+        "turn.started",
+        "turn.completed",
+        "turn.failed",
+        "error",
+        *_IGNORED_ITEM_TYPES,
+    }
+)
+
+
+class _CodexFailure(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(code)
+        self.code = code
+        self.message = message
+
+
+@dataclass(frozen=True)
+class CodexObservation:
+    sessions: tuple[Session, ...] = ()
+    errors: tuple[CollectionError, ...] = ()
+    health: SourceHealth | None = None
+    complete: bool | None = None
+    version: str | None = None
+
+
+def _read_capture(path: Path) -> bytes:
+    """Read a bounded regular file without following a runtime symlink."""
+    path = Path(path)
+    # Reject FIFOs after opening without waiting for a writer, including
+    # regular-file replacement races between metadata checks and open().
+    flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0)
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    before: os.stat_result | None = None
+    if nofollow:
+        flags |= nofollow
+    else:
+        before = path.lstat()
+        if stat_module.S_ISLNK(before.st_mode):
+            raise _CodexFailure("unsafe_path", "Codex capture path is unsafe")
+
+    try:
+        fd = os.open(path, flags)
+    except OSError as exc:
+        raise _CodexFailure("capture_unavailable", "Codex capture is unavailable") from exc
+    try:
+        metadata = os.fstat(fd)
+        if not stat_module.S_ISREG(metadata.st_mode):
+            raise _CodexFailure("unsafe_path", "Codex capture path is unsafe")
+        if before is not None and (
+            before.st_dev != metadata.st_dev or before.st_ino != metadata.st_ino
+        ):
+            raise _CodexFailure("unsafe_path", "Codex capture changed while opening")
+        if metadata.st_size > MAX_CAPTURE_BYTES:
+            raise _CodexFailure(
+                "capture_too_large",
+                "Codex capture exceeds the validated byte limit",
+            )
+        data = os.read(fd, MAX_CAPTURE_BYTES + 1)
+        if len(data) > MAX_CAPTURE_BYTES:
+            raise _CodexFailure(
+                "capture_too_large",
+                "Codex capture exceeds the validated byte limit",
+            )
+        return data
+    finally:
+        with contextlib.suppress(OSError):
+            os.close(fd)
+
+
+def _valid_thread_id(value: object) -> bool:
+    return (
+        isinstance(value, str)
+        and bool(value)
+        and len(value) <= MAX_THREAD_ID_LEN
+        and not any(ord(char) < 0x20 or 0x7F <= ord(char) <= 0x9F for char in value)
+    )
+
+
+def _error(
+    source_id: str,
+    failure: _CodexFailure,
+    observed_at: datetime,
+    *,
+    version: str | None,
+) -> CodexObservation:
+    return CodexObservation(
+        errors=(
+            CollectionError(
+                code=failure.code,
+                message=failure.message,
+                source_id=source_id,
+            ),
+        ),
+        health=SourceHealth(
+            source_id=source_id,
+            status=SourceStatus.ERROR,
+            detail=failure.message,
+            observed_at=observed_at,
+        ),
+        version=version,
+    )
+
+
+def _records(data: bytes) -> tuple[list[dict[str, Any]], bool]:
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        raise _CodexFailure("malformed_capture", "Codex capture is not valid UTF-8") from None
+
+    partial = bool(data) and not data.endswith(b"\n")
+    lines = text.splitlines()
+    if partial and lines:
+        lines = lines[:-1]
+    lines = [line for line in lines if line.strip()]
+    if len(lines) > MAX_RECORDS:
+        raise _CodexFailure(
+            "too_many_records",
+            "Codex capture exceeds the validated record limit",
+        )
+
+    records: list[dict[str, Any]] = []
+    for line in lines:
+        try:
+            raw = json.loads(line)
+        except json.JSONDecodeError:
+            raise _CodexFailure(
+                "malformed_capture", "Codex capture contains invalid JSON"
+            ) from None
+        if not isinstance(raw, dict):
+            raise _CodexFailure("malformed_capture", "Codex capture record must be an object")
+        event_type = raw.get("type")
+        if not isinstance(event_type, str) or event_type not in _ALLOWED_TYPES:
+            raise _CodexFailure(
+                "unsupported_event",
+                "Codex capture contains an unsupported event type",
+            )
+        records.append(raw)
+    return records, partial
+
+
+def observe_codex_capture(
+    *,
+    source_id: str,
+    path: Path,
+    source_version: str,
+    now: datetime | None = None,
+) -> CodexObservation:
+    """Map a validated Codex 0.155.1 exec capture to one typed session."""
+    observed_at = now or datetime.now(UTC)
+    version = source_version if isinstance(source_version, str) else None
+    try:
+        if source_version != SUPPORTED_VERSION:
+            raise _CodexFailure("unsupported_version", "Codex capture version is not supported")
+        records, partial = _records(_read_capture(path))
+        if not records:
+            raise _CodexFailure("empty_capture", "Codex capture contains no complete records")
+
+        thread_id: str | None = None
+        turn_started = False
+        lifecycle = Lifecycle.UNKNOWN
+        terminal = False
+
+        for raw in records:
+            event_type = raw["type"]
+            if event_type in _IGNORED_ITEM_TYPES:
+                continue
+
+            if event_type == "thread.started":
+                value = raw.get("thread_id")
+                if set(raw) != {"type", "thread_id"} or not _valid_thread_id(value):
+                    raise _CodexFailure("malformed_thread", "Codex thread identity is invalid")
+                if thread_id is not None:
+                    raise _CodexFailure(
+                        "multiple_threads",
+                        "Codex capture contains more than one thread",
+                    )
+                thread_id = value
+                continue
+
+            if thread_id is None:
+                raise _CodexFailure("event_order", "Codex lifecycle event precedes thread identity")
+
+            if event_type == "turn.started":
+                if set(raw) != {"type"} or turn_started or terminal:
+                    raise _CodexFailure(
+                        "unsupported_turn_sequence",
+                        "Codex capture turn sequence is unsupported",
+                    )
+                turn_started = True
+                continue
+
+            if event_type == "turn.completed":
+                if not turn_started or terminal or set(raw) != {"type", "usage"}:
+                    raise _CodexFailure(
+                        "unsupported_turn_sequence",
+                        "Codex capture turn sequence is unsupported",
+                    )
+                if not isinstance(raw.get("usage"), dict):
+                    raise _CodexFailure(
+                        "malformed_completion",
+                        "Codex turn completion shape is invalid",
+                    )
+                lifecycle = Lifecycle.DONE
+                terminal = True
+                continue
+
+            if event_type == "turn.failed":
+                if not turn_started or terminal or "error" not in raw:
+                    raise _CodexFailure(
+                        "unsupported_turn_sequence",
+                        "Codex capture turn sequence is unsupported",
+                    )
+                lifecycle = Lifecycle.FAILED
+                terminal = True
+                continue
+
+            if event_type == "error":
+                if terminal:
+                    raise _CodexFailure(
+                        "unsupported_turn_sequence",
+                        "Codex capture turn sequence is unsupported",
+                    )
+                lifecycle = Lifecycle.FAILED
+                terminal = True
+
+        if thread_id is None:
+            raise _CodexFailure("missing_thread", "Codex capture has no thread identity")
+
+        adapter_id = f"{ADAPTER_NAME}:{source_id}"
+        session = Session(
+            id=f"{adapter_id}/{thread_id}",
+            adapter_instance_id=adapter_id,
+            native_id=thread_id,
+            work_id=thread_id,
+            lifecycle=lifecycle,
+            observed_at=observed_at,
+            evidence=(
+                Evidence(
+                    source_kind=ADAPTER_NAME,
+                    source_id=source_id,
+                    field_version=FIELD_VERSION,
+                    observed_at=observed_at,
+                ),
+            ),
+        )
+        errors: tuple[CollectionError, ...] = ()
+        status = SourceStatus.OK
+        detail: str | None = None
+        complete = True
+        if partial:
+            errors = (
+                CollectionError(
+                    code="partial_record",
+                    message="Codex capture has an incomplete trailing record",
+                    source_id=source_id,
+                ),
+            )
+            status = SourceStatus.DEGRADED
+            detail = "Codex capture has an incomplete trailing record"
+            complete = False
+
+        return CodexObservation(
+            sessions=(session,),
+            errors=errors,
+            health=SourceHealth(
+                source_id=source_id,
+                status=status,
+                detail=detail,
+                observed_at=observed_at,
+            ),
+            complete=complete,
+            version=source_version,
+        )
+    except _CodexFailure as exc:
+        return _error(
+            source_id,
+            exc,
+            observed_at,
+            version=version,
+        )
+    except (OSError, TypeError, ValueError):
+        return _error(
+            source_id,
+            _CodexFailure("capture_unavailable", "Codex capture is unavailable"),
+            observed_at,
+            version=version,
+        )