talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/__init__.py

@@ -0,0 +1,5 @@
+"""OpsCloud — Autonomous CLI-first AI agent for AWS Infrastructure and Applications."""
+
+from opscloud._version import __version__
+
+__all__ = ["__version__"]

opscloud/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m opscloud."""
+
+from opscloud.cli.main import cli_main
+
+if __name__ == "__main__":
+    cli_main()

opscloud/_constants.py

@@ -0,0 +1,53 @@
+"""Global constant definitions for opscloud."""
+
+from pathlib import Path
+
+DEFAULT_AGENT_NAME = "opscloud"
+DEFAULT_ASSISTANT_ID = "opscloud"
+
+# App directories
+USER_HOME = Path.home()
+OPSCLOUD_HOME = USER_HOME / ".opscloud"
+STATE_DIR = OPSCLOUD_HOME / ".state"
+SESSIONS_DB_NAME = "sessions.db"
+SESSIONS_DB_PATH = STATE_DIR / SESSIONS_DB_NAME
+SERVER_RUNTIME_DIR = STATE_DIR / "server"
+CONFIG_FILE_PATH = OPSCLOUD_HOME / "config.toml"
+PLUGINS_CACHE_DIR = OPSCLOUD_HOME / "plugins" / "cache"
+
+# Environment variables prefixes
+ENV_PREFIX = "OPSCLOUD_"
+SERVER_ENV_PREFIX = "OPSCLOUD_SERVER_"
+
+# Tooling and shell execution
+SHELL_TIMEOUT_SECONDS = 60
+DEFAULT_PORT = 0  # Ephemeral
+
+# Large tool results prefix (used by rubrics and compaction)
+LARGE_TOOL_RESULTS_PREFIX = "/large_tool_results/"
+SYSTEM_MESSAGE_PREFIX = "[System Message]"
+
+FS_TOOL_NAMES = frozenset(
+    {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep", "execute", "run_command"}
+)
+
+READONLY_FS_TOOLS = frozenset(
+    {
+        "ls",
+        "read_file",
+        "glob",
+        "grep",
+        "view_file",
+        "list_dir",
+        "dir_list",
+        "grep_search",
+        "file_search",
+        "read_url_content",
+        "fetch_web_page",
+        "search_web",
+        "get_goal",
+        "get_rubric",
+        "update_goal",
+        "write_todos",
+    }
+)

opscloud/_debug.py

@@ -0,0 +1,145 @@
+"""Shared debug-logging configuration for verbose file-based tracing.
+
+When the `OPSCODE_DEBUG` environment variable is set, modules that handle
+streaming or remote communication can enable detailed file-based logging. This
+helper centralizes the setup so the env-var name, file path, and format are
+defined in one place.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from opscloud.config.env_vars import (
+    DEBUG,
+    DEBUG_FILE,
+    DEFAULT_DEBUG_FILE,
+    LOG_LEVEL,
+    is_env_truthy,
+)
+from opscloud.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_DEBUG_HANDLER_ATTR = "_opscloud_debug_handler"
+LOG_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+"""Canonical level-name to `logging` level mapping.
+
+The single source of truth for level names and their numeric values, shared with
+the Debug Console's level filter so severity ordering is never re-derived from
+hardcoded integers.
+"""
+
+
+def resolve_log_level(*, debug_enabled: bool | None = None) -> int:
+    """Resolve the configured runtime logging level.
+
+    Args:
+        debug_enabled: Whether `OPSCODE_DEBUG` is truthy. When omitted,
+            the current environment is checked.
+
+    Returns:
+        A standard `logging` level integer. Defaults to `DEBUG` when debug file
+        logging is enabled and `INFO` otherwise.
+    """
+    if debug_enabled is None:
+        debug_enabled = is_env_truthy(DEBUG)
+    fallback = logging.DEBUG if debug_enabled else logging.INFO
+    raw = os.environ.get(LOG_LEVEL)
+    if raw is None or not raw.strip():
+        return fallback
+    level = LOG_LEVELS.get(raw.strip().upper())
+    if level is not None:
+        return level
+    valid = ", ".join(LOG_LEVELS)
+    message = f"ignoring invalid {LOG_LEVEL}={raw!r}; expected one of {valid}"
+    # stderr for headless / pre-TUI visibility; the logger so it also lands in
+    # the always-on in-memory buffer and surfaces in the Debug Console.
+    print(f"Warning: {message}", file=sys.stderr)  # noqa: T201
+    logger.warning("%s", message)
+    return fallback
+
+
+def configure_debug_logging(target: logging.Logger) -> None:
+    """Attach a file handler to *target* when `OPSCODE_DEBUG` is set.
+
+    Intended to be called once on the `opscloud` package logger; child
+    module loggers reach the same file via propagation, so individual modules do
+    not configure logging themselves.
+
+    The log file defaults to `DEFAULT_DEBUG_FILE` but can be overridden with
+    `OPSCODE_DEBUG_FILE`. The handler appends (`mode='a'`) so logs
+    are preserved across separate process runs. Calling this again with the same
+    resolved path is a no-op: the existing tagged handler is reused rather than
+    stacking duplicates. If the resolved path changes, the stale handler is
+    closed and replaced.
+
+    Does nothing when `OPSCODE_DEBUG` is not truthy (see `is_env_truthy`).
+
+    Args:
+        target: Logger to configure.
+    """
+    debug_enabled = is_env_truthy(DEBUG)
+    level = resolve_log_level(debug_enabled=debug_enabled)
+    target.setLevel(level)
+
+    if not debug_enabled:
+        return
+
+    debug_path = Path(os.environ.get(DEBUG_FILE, DEFAULT_DEBUG_FILE))
+    for existing in list(target.handlers):
+        if not (
+            isinstance(existing, logging.FileHandler)
+            and getattr(existing, _DEBUG_HANDLER_ATTR, False)
+        ):
+            continue
+        if Path(existing.baseFilename) == debug_path:
+            # Already configured for this path; reuse rather than duplicate.
+            existing.setLevel(level)
+            return
+        # The debug path changed; drop the stale handler before re-attaching so
+        # we don't leak its file descriptor or fan logs out to two files.
+        target.removeHandler(existing)
+        existing.close()
+
+    try:
+        handler = logging.FileHandler(str(debug_path), mode="a")
+    except OSError as exc:
+        print(  # noqa: T201
+            f"Warning: could not open debug log file {debug_path}: {exc}",
+            file=sys.stderr,
+        )
+        return
+    setattr(handler, _DEBUG_HANDLER_ATTR, True)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(message)s"))
+    target.addHandler(handler)
+
+
+def installed_debug_log_path() -> Path | None:
+    """Return the path of the active debug log file, or `None` if not logging.
+
+    Reflects the file handler actually attached by `configure_debug_logging`,
+    not the current `OPSCODE_DEBUG` env value. The two diverge when the
+    variable is set after import — e.g. via a project/global `.env` loaded during
+    settings bootstrap — in which case the variable reads truthy but no handler
+    was installed and no log file exists. Callers that surface "full error in
+    <path>" hints must use this rather than the env var to avoid pointing users
+    at a file that was never created.
+    """
+    package_logger = logging.getLogger(__package__ or "opscloud")
+    for handler in package_logger.handlers:
+        if isinstance(handler, logging.FileHandler) and getattr(
+            handler, _DEBUG_HANDLER_ATTR, False
+        ):
+            return Path(handler.baseFilename)
+    return None

opscloud/_debug_buffer.py

@@ -0,0 +1,250 @@
+r"""In-memory ring buffer of recent log records for the in-app Debug Console.
+
+A lightweight `logging.Handler` keeps the most recent structured log records in
+bounded per-level `deque`s so the Debug Console (`Ctrl+\`) can show a live tail
+without requiring the opt-in file logging from `_debug.configure_debug_logging`.
+Partitioning retention by level means a burst of `DEBUG` output cannot evict the
+rarer `INFO`/`WARNING`/`ERROR` records the level filter needs. The handler is
+installed once on the `opscloud` package logger (see `__init__.py`); child
+module loggers reach it via propagation.
+
+Installation is negligible, and each emitted record only appends a structured
+record to a bounded `deque`, so the buffer is cheap enough to keep always on.
+"""
+
+from __future__ import annotations
+
+import logging
+import operator
+import os
+from collections import deque
+from dataclasses import dataclass
+
+from opscloud._debug import LOG_LEVELS
+from opscloud.config.env_vars import LOG_LEVEL
+
+DEFAULT_CAPACITY = 1000
+"""Maximum number of records retained per level in the ring buffer."""
+
+_FALLBACK_LEVEL_BUCKET = "_other"
+"""Retention bucket for records whose level name is not in `LOG_LEVELS`.
+
+Non-standard level names are retained here rather than discarded at
+classification time, and sharing one bucket keeps the number of per-level deques
+bounded no matter how many distinct custom names appear. Like every bucket, this
+one is bounded to *capacity* and evicts oldest-first, so — unlike the standard
+levels, which each get isolated retention — distinct custom levels compete for a
+single budget and can evict one another."""
+
+_DATE_FORMAT = "%H:%M:%S"
+_FORMATTER = logging.Formatter(datefmt=_DATE_FORMAT)
+
+
+def retention_bucket_for_level(level: str) -> str:
+    """Return the bounded retention bucket key for a log level name."""
+    return level if level in LOG_LEVELS else _FALLBACK_LEVEL_BUCKET
+
+
+@dataclass(frozen=True, slots=True)
+class InMemoryLogRecord:
+    """Structured log record retained by the in-memory debug buffer."""
+
+    timestamp: str
+    level: str
+    levelno: int
+    logger: str
+    message: str
+
+    @property
+    def plain_line(self) -> str:
+        """The record in the legacy plain-text debug-console format."""
+        return f"{self.timestamp} {self.level} {self.logger} {self.message}"
+
+
+class InMemoryLogBuffer(logging.Handler):
+    """Logging handler retaining the most recent structured records in memory.
+
+    Retention is partitioned by level: each recognized level name (see
+    `LOG_LEVELS`) keeps its own bounded `deque` of *capacity* records, while
+    unrecognized names share the `_FALLBACK_LEVEL_BUCKET` deque. A burst of
+    high-volume records at one recognized level (typically `DEBUG`) therefore
+    cannot evict the rarer, higher-severity records at other recognized levels,
+    so the Debug Console's level filter can still surface them. Each retained
+    record is tagged with its monotonic emission sequence number so snapshots
+    stay chronologically ordered across levels.
+    """
+
+    def __init__(self, capacity: int = DEFAULT_CAPACITY) -> None:
+        """Create the handler with a bounded backing `deque` per level.
+
+        Args:
+            capacity: Maximum records to retain per level; oldest are dropped
+                first.
+
+        Raises:
+            ValueError: If *capacity* is less than 1. A zero-capacity buffer
+                would silently discard every record while `total_emitted` kept
+                climbing, so it is rejected at the boundary.
+        """
+        if capacity < 1:
+            msg = f"capacity must be >= 1, got {capacity}"
+            raise ValueError(msg)
+        super().__init__()
+        self._capacity = capacity
+        self._levels: dict[str, deque[tuple[int, InMemoryLogRecord]]] = {}
+        self._total = 0
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Append the structured *record* to its level's ring buffer."""
+        self.acquire()
+        try:
+            structured = self._make_record(record)
+            bucket = self._level_bucket(structured.level)
+            bucket.append((self._total, structured))
+            self._total += 1
+        except Exception:  # noqa: BLE001  # never let logging crash the app
+            self.handleError(record)
+        finally:
+            self.release()
+
+    def _level_bucket(self, level: str) -> deque[tuple[int, InMemoryLogRecord]]:
+        """Return the retention deque for *level*, creating it on first use."""
+        key = retention_bucket_for_level(level)
+        bucket = self._levels.get(key)
+        if bucket is None:
+            bucket = deque(maxlen=self._capacity)
+            self._levels[key] = bucket
+        return bucket
+
+    @property
+    def total_emitted(self) -> int:
+        """Total records ever emitted (monotonic; survives buffer eviction)."""
+        self.acquire()
+        try:
+            return self._total
+        finally:
+            self.release()
+
+    def snapshot_records_since(self, index: int) -> tuple[list[InMemoryLogRecord], int]:
+        """Return retained structured records and the next absolute index.
+
+        Absolute indices are stable even as old records are evicted, so callers
+        can poll incrementally without re-reading records they already consumed.
+        Returning the records and the resume index together under the handler
+        lock prevents a concurrent append from being skipped between separate
+        reads.
+
+        Args:
+            index: Absolute emission index to start from.
+
+        Returns:
+            A tuple of the structured records from *index* onward that are still
+            retained, and the current total emitted count to resume from.
+        """
+        self.acquire()
+        try:
+            return self._records_since_unlocked(index), self._total
+        finally:
+            self.release()
+
+    def _records_since_unlocked(self, index: int) -> list[InMemoryLogRecord]:
+        """Return retained records from *index* while the handler lock is held.
+
+        Merges the per-level deques and restores chronological order using each
+        record's emission sequence number, so callers see one ordered tail even
+        though retention is partitioned by level.
+        """
+        tagged = [
+            entry
+            for bucket in self._levels.values()
+            for entry in bucket
+            if entry[0] >= index
+        ]
+        tagged.sort(key=operator.itemgetter(0))
+        return [record for _seq, record in tagged]
+
+    @staticmethod
+    def _make_record(record: logging.LogRecord) -> InMemoryLogRecord:
+        """Convert a standard logging record into a structured debug record.
+
+        Returns:
+            Structured record for display and filtering.
+        """
+        message = record.getMessage()
+        if record.exc_info:
+            if not record.exc_text:
+                record.exc_text = _FORMATTER.formatException(record.exc_info)
+            if record.exc_text:
+                message = f"{message}\n{record.exc_text}"
+        if record.stack_info:
+            message = f"{message}\n{_FORMATTER.formatStack(record.stack_info)}"
+        return InMemoryLogRecord(
+            timestamp=_FORMATTER.formatTime(record, _DATE_FORMAT),
+            level=record.levelname,
+            levelno=record.levelno,
+            logger=record.name,
+            message=message,
+        )
+
+
+_buffer: InMemoryLogBuffer | None = None
+
+
+def install_log_buffer(
+    target: logging.Logger, capacity: int = DEFAULT_CAPACITY
+) -> InMemoryLogBuffer:
+    """Attach the in-memory buffer handler to *target* (idempotent).
+
+    Lowers *target*'s level to at most `INFO` so the console shows a useful tail
+    even when `OPSCODE_DEBUG` is off; never raises the level. In
+    `__init__.py` this runs *before* `configure_debug_logging`, which then sets
+    the final level (honoring `OPSCODE_DEBUG` and
+    `OPSCODE_LOG_LEVEL`) over this `INFO` floor — so any startup warnings
+    `configure_debug_logging` emits are captured by the already-installed buffer.
+    On a fresh `NOTSET` logger the `NOTSET` branch forces `INFO` without
+    consulting `OPSCODE_LOG_LEVEL`; the `> INFO and no env` branch only
+    matters on reconfiguration (e.g. an `importlib.reload`), where it preserves
+    an explicit `OPSCODE_LOG_LEVEL` rather than clobbering it with `INFO`.
+
+    Lowering the level does not spill log output onto the terminal: because this
+    handler is present in the propagation chain, `Logger.callHandlers` finds a
+    handler (`found > 0`) and Python's `lastResort` stderr handler is never
+    consulted. The exception is an embedding process that attaches its own
+    `INFO`-or-lower handler to the root logger, which would then see the
+    propagated records.
+
+    Note: this runs as an import-time side effect (see `__init__.py`), so every
+    `import opscloud` attaches the handler and may lower the package
+    logger's level to `INFO` for the lifetime of the process.
+
+    Args:
+        target: Logger to attach the buffer to (the package logger).
+        capacity: Maximum records to retain.
+
+    Returns:
+        The installed (or already-installed) buffer handler.
+    """
+    global _buffer  # noqa: PLW0603  # module-level singleton accessor
+    for existing in target.handlers:
+        if isinstance(existing, InMemoryLogBuffer):
+            _buffer = existing
+            return existing
+
+    handler = InMemoryLogBuffer(capacity)
+    handler.setLevel(logging.DEBUG)
+    target.addHandler(handler)
+    if target.level == logging.NOTSET or (
+        target.level > logging.INFO and not os.environ.get(LOG_LEVEL)
+    ):
+        target.setLevel(logging.INFO)
+    _buffer = handler
+    return handler
+
+
+def get_log_buffer() -> InMemoryLogBuffer | None:
+    """Return the installed buffer handler.
+
+    Returns:
+        The installed buffer handler, or `None` if not yet installed.
+    """
+    return _buffer