devopsiq 0.1.0__py3-none-any.whl

tools/base.py

@@ -0,0 +1,112 @@
+"""Tool contract for the DevOps investigation agent.
+
+All tools are READ-ONLY by construction: an executor inspects the system and
+returns text evidence; nothing in this module can mutate state, and tools
+never accept arbitrary commands (they select from hard-coded, allowlisted
+invocations).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+# Ceiling for how much of a tool result is fed back to the model in one turn.
+MAX_TOOL_OUTPUT_CHARS = 8_000
+
+
+class ToolError(Exception):
+    """Raised by an executor when a tool could not produce its result."""
+
+
+def truncate_output(text: str, limit: int = MAX_TOOL_OUTPUT_CHARS) -> str:
+    """Cut very long output so the TOTAL returned length stays <= limit.
+
+    Head and tail of the original are kept; a short digest line connects
+    them. 64 characters are reserved for that line, which is enough for any
+    realistic input size.
+    """
+    if len(text) <= limit:
+        return text
+
+    body = max(2, limit - 64)  # budget left for actual content
+    head_len = body // 2
+    tail_len = body - head_len
+
+    omitted = len(text) - body
+    marker = f"\n… [{omitted} characters omitted] …\n"
+    if len(marker) > limit - body:
+        marker = "\n… (output truncated) …\n"
+
+    return text[:head_len] + marker + text[-tail_len:]
+
+
+def read_command_output(argv: Sequence[str], timeout: int = 10) -> str:
+    """Run an allowlisted read-only command and return its output as evidence.
+
+    Raises ToolError (so the caller never feeds unvalidated input to a
+    shell) when the binary is missing, the command times out, or it exits
+    non-zero — in the failure cases, the captured output is embedded in the
+    error so the model sees real diagnostics rather than a generic message.
+
+    Successful output is prefixed with the literal command line (so the
+    model can tell it is real captured output, not a canned string) and
+    truncated to MAX_TOOL_OUTPUT_CHARS.
+    """
+    binary = argv[0]
+    if shutil.which(binary) is None:
+        raise ToolError(
+            f"required executable {binary!r} is not installed on this host"
+        )
+    try:
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ToolError(f"command {binary} timed out after {timeout}s") from exc
+
+    output = ((proc.stdout or "") + (proc.stderr or "")).strip()
+    if proc.returncode != 0:
+        raise ToolError(
+            f"command {binary} exited with code {proc.returncode}:\n"
+            f"{output or '(no output)'}"
+        )
+    if not output:
+        output = f"(command {' '.join(argv)} returned no output, exit code 0)"
+    return truncate_output(f"$ {' '.join(argv)}\n{output}")
+
+
+@dataclass(frozen=True)
+class Tool:
+    """A read-only capability the model can call while investigating.
+
+    Attributes:
+        name: stable identifier the model uses to request this tool.
+        description: when/how to use it; sent to the model alongside the schema.
+        parameters: JSON Schema describing the arguments the tool accepts.
+        executor: local callable(args: dict) -> str. It receives the *parsed*
+            JSON arguments and returns the text fed back to the model as
+            evidence. Must be read-only and must never fabricate output.
+    """
+
+    name: str
+    description: str
+    parameters: dict
+    executor: Callable[[dict], str]
+
+    def schema(self) -> dict:
+        """Render this tool in the OpenAI-compatible `tools` request format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }

tools/cloud.py

@@ -0,0 +1,101 @@
+"""Read-only cloud-account tools (Phase 8).
+
+Identity and listing probes for the three major cloud CLIs: who am I / which
+account is active (aws sts get-caller-identity, gcloud config list, az account
+show) and a first-level resource listing (az group list). These answer "which
+cloud account am I even looking at" — usually the first question when an
+incident report and the infrastructure disagree.
+
+Safety model:
+- Only fixed argv templates with read-only verbs exist. There is no create,
+  delete, update, start, stop, tag, or IAM-mutation path, and no
+  user-supplied argument anywhere: neither AWS, gcloud nor az ever receives
+  model-chosen text, so flag/dispatch injection is impossible.
+- `aws sts get-caller-identity` needs no region; listing tools are kept to
+  account/subscription level on purpose — region-scoped resource sweeps
+  (ec2 describe-*, compute instances list ...) can be added later behind the
+  same template pattern.
+- The CLIs must be installed and configured (aws credentials, gcloud/az
+  logins). Missing pieces surface as the exact CLI error — never invented.
+- Cloud CLIs are slow on a cold start (helper processes, token refresh), so
+  the subprocess timeout is 30s rather than the usual 10s.
+"""
+
+from tools.base import Tool, read_command_output
+from tools.registry import register
+
+_TIMEOUT_S = 30
+
+
+def _aws_identity(args: dict) -> str:
+    return read_command_output(
+        ("aws", "sts", "get-caller-identity", "--output", "json"),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _gcloud_identity(args: dict) -> str:
+    return read_command_output(
+        ("gcloud", "config", "list", "--format=json"),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _az_account(args: dict) -> str:
+    return read_command_output(("az", "account", "show"), timeout=_TIMEOUT_S)
+
+
+def _az_groups(args: dict) -> str:
+    return read_command_output(("az", "group", "list"), timeout=_TIMEOUT_S)
+
+
+AWS_IDENTITY = Tool(
+    name="aws_identity",
+    description=(
+        "AWS caller identity as JSON (aws sts get-caller-identity): account "
+        "id, user/role ARN. Use to answer 'which AWS account and principal "
+        "are the configured credentials for'. Requires aws CLI with working "
+        "credentials. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_aws_identity,
+)
+
+GCLOUD_IDENTITY = Tool(
+    name="gcloud_identity",
+    description=(
+        "Active gcloud configuration as JSON (gcloud config list): account, "
+        "project, region, zone. Use to answer 'which GCP project/region is "
+        "this host pointed at'. Requires the gcloud CLI. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_gcloud_identity,
+)
+
+AZ_ACCOUNT = Tool(
+    name="az_account",
+    description=(
+        "The active Azure subscription as JSON (az account show): id, name, "
+        "state, tenant. Use to answer 'which Azure subscription am I looking "
+        "at'. Requires the az CLI and a logged-in account. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_az_account,
+)
+
+AZ_GROUPS = Tool(
+    name="az_groups",
+    description=(
+        "List Azure resource groups in the active subscription as JSON (az "
+        "group list): name, location, tags. Use to see the top-level layout "
+        "of an Azure subscription during an investigation. Requires az CLI. "
+        "Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_az_groups,
+)
+
+register(AWS_IDENTITY)
+register(GCLOUD_IDENTITY)
+register(AZ_ACCOUNT)
+register(AZ_GROUPS)

tools/docker.py

@@ -0,0 +1,280 @@
+"""Read-only Docker tools (Phases 5, 8, 9).
+
+Ten tools for container problems on the host: list containers (docker ps),
+inspect one (JSON), tail logs, live resource stats (docker stats --no-stream),
+the local image list, networks, volumes, disk usage (Phase 8), and (Phase 9)
+Docker Compose project listing + a project's services. Same contract/safety
+model as the other modules.
+
+Safety model:
+- Only fixed argv templates exist with the read-only docker verbs ps, inspect,
+  logs, stats, images, network ls, volume ls, system df, compose ls, compose
+  ps. There is no run, start, stop, restart, rm, rmi, pull, push, exec, build,
+  create, prune or compose-up/down path.
+- `docker stats` is hard-coded with `--no-stream`: without it the command
+  follows forever and would hang a turn.
+- Container/image names are validated (letters, digits, '.', '-', '_', no
+  leading dash) — blocks flag injection and path traversal.
+- Docker must be installed and the daemon running; if not, the exact error
+  is returned — nothing is invented. A dangling or dead daemon surfaces as
+  a real ToolError, which the model must report honestly.
+"""
+
+import re
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# Docker names: letters, digits, '.', '-', '_'; must start/end alphanumeric.
+_NAME_RE = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9._\-]{0,127}")
+_TIMEOUT_S = 10
+
+
+def _check_name(value, kind: str) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) > 128
+        or not _NAME_RE.fullmatch(value)
+    ):
+        raise ToolError(
+            f"invalid Docker {kind} name {value!r}: expected letters, digits, "
+            "'.', '-' or '_', max 128 chars"
+        )
+    return value
+
+
+def _checked_lines(args: dict) -> int:
+    try:
+        lines = int(args.get("lines", 100))
+    except (TypeError, ValueError):
+        raise ToolError("lines must be an integer between 1 and 500")
+    if not 1 <= lines <= 500:
+        raise ToolError("lines must be between 1 and 500")
+    return lines
+
+
+def _docker_ps(args: dict) -> str:
+    return read_command_output(("docker", "ps", "-a"), timeout=_TIMEOUT_S)
+
+
+def _docker_inspect(args: dict) -> str:
+    name = _check_name(args.get("name"), "container or image")
+    return read_command_output(("docker", "inspect", name), timeout=_TIMEOUT_S)
+
+
+def _docker_logs(args: dict) -> str:
+    name = _check_name(args.get("container"), "container")
+    return read_command_output(
+        ("docker", "logs", "--tail", str(_checked_lines(args)), name),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _docker_stats(args: dict) -> str:
+    return read_command_output(("docker", "stats", "--no-stream"), timeout=_TIMEOUT_S)
+
+
+def _docker_images(args: dict) -> str:
+    return read_command_output(("docker", "images"), timeout=_TIMEOUT_S)
+
+
+DOCKER_PS = Tool(
+    name="docker_ps",
+    description=(
+        "List all containers (running and stopped) with status: container id, "
+        "image, command, status (Up/X minutes, Exited (code) ...), names. The "
+        "first tool for 'is my container running / why did it stop'. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {},
+        "additionalProperties": False,
+    },
+    executor=_docker_ps,
+)
+
+DOCKER_INSPECT = Tool(
+    name="docker_inspect",
+    description=(
+        "Inspect one container or image by name as JSON — state, exit code, "
+        "restart count, mounts, env, image id. Use with docker_ps to see the "
+        "details behind a container's state. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Container or image name/id to inspect.",
+            }
+        },
+        "required": ["name"],
+        "additionalProperties": False,
+    },
+    executor=_docker_inspect,
+)
+
+DOCKER_LOGS = Tool(
+    name="docker_logs",
+    description=(
+        "Fetch the tail of a container's stdout/stderr logs as plain text. Use "
+        "with docker_ps/docker_inspect to see the error that made a container "
+        "exit or crash-loop. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "container": {"type": "string", "description": "Container name/id."},
+            "lines": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 500,
+                "default": 100,
+                "description": "How many lines to tail (1–500).",
+            },
+        },
+        "required": ["container"],
+        "additionalProperties": False,
+    },
+    executor=_docker_logs,
+)
+
+DOCKER_STATS = Tool(
+    name="docker_stats",
+    description=(
+        "One snapshot of live resource usage for running containers: CPU %, "
+        "memory used/limit, net/block I/O. Use for 'which container burns CPU "
+        "or RAM'. Read-only; never blocks (always --no-stream)."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {},
+        "additionalProperties": False,
+    },
+    executor=_docker_stats,
+)
+
+DOCKER_IMAGES = Tool(
+    name="docker_images",
+    description=(
+        "List local container images: repository, tag, image id, size. Use to "
+        "check whether an image/tag exists locally or is dangling. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {},
+        "additionalProperties": False,
+    },
+    executor=_docker_images,
+)
+
+# --- Phase 8: Docker depth — networks, volumes, disk usage -------------------
+
+def _docker_networks(args: dict) -> str:
+    return read_command_output(("docker", "network", "ls"), timeout=_TIMEOUT_S)
+
+
+def _docker_volumes(args: dict) -> str:
+    return read_command_output(("docker", "volume", "ls"), timeout=_TIMEOUT_S)
+
+
+def _docker_disk_usage(args: dict) -> str:
+    return read_command_output(("docker", "system", "df"), timeout=_TIMEOUT_S)
+
+
+DOCKER_NETWORKS = Tool(
+    name="docker_networks",
+    description=(
+        "List Docker networks on the host (docker network ls): name, driver, "
+        "scope. Use for 'which network does my container use', connectivity "
+        "and bridge/overlay questions. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_docker_networks,
+)
+
+DOCKER_VOLUMES = Tool(
+    name="docker_volumes",
+    description=(
+        "List Docker volumes on the host (docker volume ls): volume names and "
+        "drivers. Use for 'does the volume my data lives in exist', dangling "
+        "volume checks. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_docker_volumes,
+)
+
+DOCKER_DISK_USAGE = Tool(
+    name="docker_disk_usage",
+    description=(
+        "Docker disk usage on the host (docker system df): how much space "
+        "images, containers, volumes and the build cache consume, with "
+        "reclaimable amounts. Use for 'is the disk full because of Docker'. "
+        "Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_docker_disk_usage,
+)
+
+# --- Phase 9: Docker Compose — compose project listing and one project's
+# services. Same contract: fixed argv, validated project name, ps/ls only. ---
+
+def _docker_compose_ls(args: dict) -> str:
+    return read_command_output(("docker", "compose", "ls"), timeout=_TIMEOUT_S)
+
+
+def _docker_compose_ps(args: dict) -> str:
+    project = args.get("project")
+    if project is not None:
+        _check_name(project, "compose project")
+        argv = ("docker", "compose", "-p", project, "ps", "-a")
+    else:
+        # No -p: reads the compose project of the current working directory.
+        argv = ("docker", "compose", "ps", "-a")
+    return read_command_output(argv, timeout=_TIMEOUT_S)
+
+
+DOCKER_COMPOSE_LS = Tool(
+    name="docker_compose_ls",
+    description=(
+        "List running Docker Compose projects on the host (docker compose "
+        "ls): project name, status, config files. Use to see which compose "
+        "stacks exist before looking at one's services. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_docker_compose_ls,
+)
+
+DOCKER_COMPOSE_PS = Tool(
+    name="docker_compose_ps",
+    description=(
+        "List the containers of a Docker Compose project (docker compose "
+        "ps -a): service, state, ports — running AND stopped. Use with "
+        "docker_compose_ls to see what a stack is made of, or which service "
+        "inside a project exited. Without 'project', uses the compose file "
+        "in the current working directory. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "project": {
+                "type": "string",
+                "description": "Optional compose project name (from "
+                "docker_compose_ls).",
+            }
+        },
+        "additionalProperties": False,
+    },
+    executor=_docker_compose_ps,
+)
+
+register(DOCKER_PS)
+register(DOCKER_INSPECT)
+register(DOCKER_LOGS)
+register(DOCKER_STATS)
+register(DOCKER_IMAGES)
+register(DOCKER_NETWORKS)
+register(DOCKER_VOLUMES)
+register(DOCKER_DISK_USAGE)
+register(DOCKER_COMPOSE_LS)
+register(DOCKER_COMPOSE_PS)