superkick 0.1.0

data/lib/superkick/integrations/datadog/spawner.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Datadog
+      # Watches Datadog Error Tracking for open error groups and spawns AI coding
+      # agents to fix them.
+      #
+      # Polls the Datadog Error Tracking API for error groups matching configurable
+      # filters (service, environment, status, source). Tracks dispatched group IDs
+      # in-memory to avoid re-dispatching.
+      #
+      # Config keys:
+      #   site             (optional) — Datadog site, default "datadoghq.com"
+      #   api_key          (optional) — API key, falls back to $DD_API_KEY
+      #   application_key  (optional) — Application key, falls back to $DD_APP_KEY
+      #   service          (optional) — filter to a specific service name
+      #   environment      (optional) — filter to an environment, default "production"
+      #   source           (optional) — error source filter (e.g. "ruby", "python")
+      #   minimum_events   (optional) — minimum event count to dispatch, default 1
+      #   query            (optional) — raw Datadog search query string
+      class Spawner < Superkick::Spawner
+        attr_reader :conn
+
+        DEFAULT_SITE = "datadoghq.com"
+        DEFAULT_ENVIRONMENT = "production"
+        DEFAULT_MINIMUM_EVENTS = 1
+        PER_PAGE = 25
+
+        def self.type = :datadog
+
+        def self.description
+          "Watches Datadog Error Tracking for open error groups and spawns AI " \
+            "coding agents to fix them. Supports filtering by service, " \
+            "environment, source, and minimum event count."
+        end
+
+        def self.required_config = %i[]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "datadog-error-#{event[:group_id]}"
+        end
+
+        def self.setup_label = "Datadog Errors"
+
+        def self.setup_config
+          <<~YAML
+            datadog_errors:
+              type: datadog
+              # api_key: <%= env("DD_API_KEY") %>
+              # application_key: <%= env("DD_APP_KEY") %>
+              # site: datadoghq.com              # Datadog site (default)
+              # service: my-service              # filter by service name
+              # environment: production           # default
+              # source: ruby                     # error source filter
+              # minimum_events: 1                # minimum events before spawning
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def tick
+          groups = fetch_error_groups
+          groups.each do |group|
+            attrs = group["attributes"] || {}
+
+            next if filtered_by_minimum_events?(attrs)
+
+            @seen_group_ids.add(group["id"])
+
+            dispatch(
+              event_type: :error_opened,
+              group_id: group["id"],
+              error_class: attrs["name"].to_s,
+              message: attrs["message"].to_s,
+              status: attrs["status"].to_s,
+              service: attrs["service"].to_s,
+              environment: attrs["env"].to_s,
+              first_seen: attrs["first_seen"].to_s,
+              last_seen: attrs["last_seen"].to_s,
+              events: attrs["count"] || 0,
+              users: attrs["impacted_users"],
+              source: attrs["source"].to_s,
+              url: error_group_url(group["id"])
+            )
+          end
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @seen_group_ids = Set.new
+        end
+
+        private
+
+        # -- Datadog Error Tracking API -------------------------------------------
+
+        def fetch_error_groups
+          query = build_query
+          params = {
+            "filter[query]" => query,
+            "filter[status]" => "open",
+            "page[limit]" => PER_PAGE.to_s,
+            "sort" => "-last_seen"
+          }
+
+          Superkick.logger.debug(log_tag) { "Fetching error groups: #{params.inspect}" }
+
+          resp = get("/api/v2/error-tracking/issues", params)
+          return [] unless resp
+
+          body = resp.body
+          groups = body["data"]
+          return [] unless groups.is_a?(Array)
+
+          new_groups = groups.reject { @seen_group_ids.include?(it["id"]) }
+
+          Superkick.logger.info(log_tag) { "Found #{groups.size} error groups, #{new_groups.size} new" }
+          new_groups
+        end
+
+        def build_query
+          parts = []
+
+          env = self[:environment]
+          env = DEFAULT_ENVIRONMENT if env.nil?
+          parts << "env:#{env}" if env && !env.to_s.empty?
+
+          parts << "service:#{self[:service]}" if self[:service] && !self[:service].to_s.empty?
+          parts << "source:#{self[:source]}" if self[:source] && !self[:source].to_s.empty?
+
+          # Allow raw query passthrough for advanced filtering
+          parts << self[:query].to_s if self[:query] && !self[:query].to_s.empty?
+
+          parts.join(" ")
+        end
+
+        # -- Client-side filters --------------------------------------------------
+
+        def filtered_by_minimum_events?(attrs)
+          min = self[:minimum_events] || DEFAULT_MINIMUM_EVENTS
+          count = attrs["count"] || 0
+          count < min
+        end
+
+        # -- URL helpers ----------------------------------------------------------
+
+        def error_group_url(group_id)
+          site = self[:site] || DEFAULT_SITE
+          "https://app.#{site}/error-tracking/issue/#{group_id}"
+        end
+
+        # -- HTTP -----------------------------------------------------------------
+
+        def get(path, params = {})
+          resp = @conn.get(path) do |req|
+            params.each { |k, v| req.params[k] = v }
+          end
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Datadog auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Datadog rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Datadog 404: resource not found" }
+            false
+          else
+            Superkick.logger.warn(log_tag) { "Datadog HTTP #{resp.status}" }
+            false
+          end
+        end
+
+        def build_connection
+          site = self[:site] || DEFAULT_SITE
+          api_key = self[:api_key] || ENV["DD_API_KEY"]
+          app_key = self[:application_key] || ENV["DD_APP_KEY"]
+
+          Faraday.new(url: "https://api.#{site}") do |f|
+            f.headers["DD-API-KEY"] = api_key if api_key
+            f.headers["DD-APPLICATION-KEY"] = app_key if app_key
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/datadog/templates/alert_changed.liquid

@@ -0,0 +1,8 @@
+SUPERKICK [{{ "now" | time }}]: Datadog alert status changed — {{ name }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Status: {{ status }} (was {{ previous_status }})
+
+The Datadog monitor "{{ name }}" changed status from {{ previous_status }} to {{ status }}.
+Take this into account as you continue your investigation.

data/lib/superkick/integrations/datadog/templates/alert_escalated.liquid

@@ -0,0 +1,8 @@
+SUPERKICK [{{ "now" | time }}]: Datadog alert escalated — {{ name }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Status: {{ status }} (was {{ previous_status }})
+
+The Datadog monitor "{{ name }}" has escalated from {{ previous_status }} to {{ status }}.
+This alert is getting worse — prioritize your investigation accordingly.

data/lib/superkick/integrations/datadog/templates/alert_recovered.liquid

@@ -0,0 +1,14 @@
+SUPERKICK [{{ "now" | time }}]: Datadog alert recovered — {{ name }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Status: {{ status }} (was {{ previous_status }})
+
+The Datadog monitor "{{ name }}" has recovered and is now OK.
+
+If you have already implemented a fix, this confirms it is working.
+Please signal your goal as completed using `superkick_signal_goal`
+with status "completed" and a brief summary of what you did.
+
+If you have not yet started working on a fix, this alert resolved on its own.
+Signal your goal as completed with a summary noting the alert self-recovered.

data/lib/superkick/integrations/datadog/templates/alert_triggered.liquid

@@ -0,0 +1,29 @@
+SUPERKICK [{{ "now" | time }}]: Datadog alert — {{ name }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Status: {{ status }}{% if alert_type %} | Type: {{ alert_type }}{% endif %}{% if priority %} | Priority: P{{ priority }}{% endif %}
+{% if tags.size > 0 -%}
+Tags: {{ tags | join: ", " }}
+{% endif -%}
+
+## Alert: {{ name }}
+
+{% if message -%}
+### Runbook / Notification Message
+{{ message }}
+{% endif -%}
+
+{% if query -%}
+### Monitor Query
+```
+{{ query }}
+```
+{% endif -%}
+
+Please triage this alert:
+1. Review the monitor query and notification message above for context
+2. Check application logs and recent code changes for potential root causes
+3. If this is a code issue, identify the root cause and implement a fix
+4. If this is infrastructure/config related, document your findings and recommendations
+5. Run tests to verify your fix doesn't introduce regressions

data/lib/superkick/integrations/datadog/templates/error_opened.liquid

@@ -0,0 +1,15 @@
+SUPERKICK [{{ "now" | time }}]: Datadog error — {{ error_class }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Service: {{ service }}{% unless environment == "" %} | Env: {{ environment }}{% endunless %}
+Events: {{ events }}{% if users %} | Users: {{ users }}{% endif %}
+First seen: {{ first_seen }} | Last seen: {{ last_seen }}
+
+## Error
+
+**{{ error_class }}**: {% if message == "" %}(no message){% else %}{{ message }}{% endif %}
+
+Please investigate this error, identify the root cause, implement a fix, and
+write tests to prevent regression. Check the Datadog Error Tracking dashboard
+for full stack traces and contextual data.

data/lib/superkick/integrations/datadog.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "datadog/notifier"
+require_relative "datadog/spawner"
+require_relative "datadog/alert_spawner"
+require_relative "datadog/alert_monitor"
+require_relative "datadog/alert_goal"
+
+module Superkick
+  Notifier.register(Integrations::Datadog::Notifier)
+  Spawner.register(Integrations::Datadog::Spawner)
+  Spawner.register(Integrations::Datadog::AlertSpawner)
+  Monitor.register(Integrations::Datadog::AlertMonitor)
+end

data/lib/superkick/integrations/docker/README.md

@@ -0,0 +1,256 @@
+# Docker Runtime
+
+Type: `:docker`
+
+Provisions spawned agents in Docker containers via the Docker Engine API.
+
+## Server connectivity
+
+Containerized agents need to communicate with the Superkick server. Two modes are supported, and local mode works automatically with no extra configuration.
+
+### Local mode (automatic)
+
+When the Superkick server uses the default local transport (Unix sockets), the Docker runtime automatically bind-mounts the Superkick `run/` directory into the container and sets `SUPERKICK_DIR` so the agent process can find the server's control socket. No manual volume configuration needed — just set the image and go:
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent:latest
+```
+
+Under the hood, the runtime injects:
+- A bind mount: `~/.superkick/run` → `/superkick/run` (inside the container)
+- An env var: `SUPERKICK_DIR=/superkick`
+
+If you need to override the container-internal path, set `SUPERKICK_DIR` explicitly in the `env:` config — your value takes precedence over the auto-injected default.
+
+### Hosted mode (HTTPS + WebSocket)
+
+When the container can't access the host filesystem (remote Docker daemons, orchestrators, multi-host setups), configure hosted mode. The agent connects to the server over HTTPS for control and WebSocket for buffer communication. In this mode, no auto-injection occurs — the agent uses the `server:` config instead of Unix sockets:
+
+```yaml
+server:
+  url: https://superkick.example.com
+  api_key: <%= env("SUPERKICK_API_KEY") %>
+
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent:latest
+```
+
+## Configuration
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent:latest        # required — Docker image to use
+    host: unix:///var/run/docker.sock    # Docker daemon address (default)
+    pull_policy: missing                 # when to pull the image
+    memory: 4G                           # container memory limit
+    cpu: 2                               # CPU core limit (NanoCPUs)
+    network: superkick-net               # Docker network to attach
+    stop_timeout: 30                     # seconds before SIGKILL on stop
+    auto_remove: true                    # remove container after exit
+    env:                                 # environment variables added to every container
+      GITHUB_TOKEN: <%= env("GITHUB_TOKEN") %>
+    volumes:                             # bind mounts (host:container[:options])
+      - /home/user/.ssh:/root/.ssh:ro
+      - /home/user/.gitconfig:/root/.gitconfig:ro
+    labels:                              # container labels
+      app: superkick
+      environment: production
+    privileged: false                    # run in privileged mode (for DinD)
+    cap_add:                             # Linux capabilities to add
+      - SYS_ADMIN
+    security_opt:                        # security options
+      - seccomp:unconfined
+    container_runtime: sysbox-runc       # OCI runtime (for unprivileged DinD)
+    registry:                            # private registry authentication
+      username: <%= env("DOCKER_REGISTRY_USER") %>
+      password: <%= env("DOCKER_REGISTRY_PASSWORD") %>
+      server: ghcr.io
+    tls:                                 # TLS client certificates for TCP connections
+      ca: /path/to/ca.pem
+      cert: /path/to/cert.pem
+      key: /path/to/key.pem
+```
+
+## Settings reference
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `image` | *(required)* | Docker image name with optional tag (e.g. `superkick/agent:latest`) |
+| `host` | `unix:///var/run/docker.sock` | Docker daemon address. Supports `unix://` and `tcp://` schemes |
+| `pull_policy` | `missing` | When to pull the image: `always` (every provision), `missing` (only if not present locally), `never` (fail if not present) |
+| `memory` | *(none)* | Memory limit. Accepts human-readable strings (`512M`, `4G`) or byte integers |
+| `cpu` | *(none)* | CPU limit in cores (e.g. `2` = 2,000,000,000 NanoCPUs) |
+| `network` | *(none)* | Docker network name to attach the container to |
+| `stop_timeout` | `30` | Seconds to wait after SIGTERM before sending SIGKILL |
+| `auto_remove` | `true` | Automatically remove the container when it exits |
+| `env` | `{}` | Additional environment variables merged into every container. Spawner-level env vars take precedence on conflict |
+| `volumes` | `[]` | Bind mount strings in `host:container[:options]` format |
+| `labels` | `{}` | Labels applied to every container. `superkick.agent_id` is always added automatically |
+| `privileged` | `false` | Run container in privileged mode. Required for Docker-in-Docker (DinD) |
+| `cap_add` | `[]` | Linux capabilities to add to the container (e.g. `["SYS_ADMIN"]`) |
+| `security_opt` | `[]` | Security options (e.g. `["seccomp:unconfined"]`) |
+| `container_runtime` | *(none)* | OCI runtime to use for the container (e.g. `sysbox-runc`). Maps to Docker's `HostConfig.Runtime` |
+| `registry` | *(none)* | Private registry credentials (`username`, `password`, `server`) sent as Base64-encoded auth header |
+| `tls` | *(none)* | TLS client certificate paths (`ca`, `cert`, `key`) for TCP connections to the Docker daemon |
+
+## Container naming
+
+Containers are named `superkick-<agent-id>` and labeled with `superkick.agent_id` for identification and cleanup.
+
+## Image pull policy
+
+| Policy | Behavior |
+|--------|----------|
+| `always` | Pull the image before every provision, even if it exists locally |
+| `missing` | Check if the image exists locally; pull only if absent (default) |
+| `never` | Never pull; fail if the image is not available locally |
+
+## Connection modes
+
+The Docker client supports two connection modes:
+
+- **Unix socket** (default) — connects to the Docker daemon via `unix:///var/run/docker.sock`. Uses a custom Faraday adapter for HTTP-over-Unix-socket communication.
+- **TCP + TLS** — connects to a remote Docker daemon via `tcp://host:port`. When `tls:` config is provided, uses mutual TLS with client certificates.
+
+## Docker-in-Docker (DinD)
+
+When agents need to run Docker commands inside their containers (e.g. `docker compose up`, devcontainer builds, running test suites that spin up services), there are several approaches with different security and isolation trade-offs.
+
+### Option 1: Socket passthrough (Docker-outside-of-Docker)
+
+Mount the host Docker socket into the container. The agent shares the host's Docker daemon, so containers it creates are **siblings** of the agent container on the host. This is the simplest approach and what the [original `dind` author recommends](https://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci/) for most CI/CD use cases.
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent:latest
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+**Pros:** Zero overhead, no special image or capabilities needed, full Docker feature parity.
+
+**Cons:** No isolation — the agent can see and manipulate all host containers. Sibling containers persist on the host after the agent exits (no automatic cleanup). Volume mounts inside agent-created containers reference host paths, not the agent container's filesystem.
+
+**When to use:** Single-tenant environments where you trust the agent, or when you need maximum Docker compatibility with minimal setup.
+
+### Option 2: True DinD (privileged)
+
+Run a full Docker daemon inside the agent container. The agent gets a completely isolated Docker environment with its own image cache, networks, and volumes. When the outer container is removed, everything inside — including all nested containers — is destroyed automatically.
+
+The agent image must include `dockerd`. The official [`docker:dind`](https://hub.docker.com/_/docker) image is a good base, or you can install Docker Engine in your own image.
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent-dind:latest
+    privileged: true
+    volumes:
+      # Use a named volume or tmpfs for the inner daemon's data —
+      # overlay-on-overlay is slow and fragile
+      - superkick-dind-storage:/var/lib/docker
+```
+
+The container's entrypoint should start `dockerd` in the background before launching the AI CLI. A minimal example:
+
+```dockerfile
+FROM docker:dind
+# ... install your AI CLI, superkick, etc.
+
+COPY entrypoint.sh /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]
+```
+
+```bash
+#!/bin/sh
+# entrypoint.sh — start dockerd, wait for it, then exec the agent command
+dockerd &
+# Wait for the daemon socket to appear
+while ! docker info >/dev/null 2>&1; do sleep 0.5; done
+exec "$@"
+```
+
+**Pros:** Full isolation. Automatic cleanup. The agent's Docker environment is ephemeral — no state leaks between runs.
+
+**Cons:** `privileged: true` grants the container nearly all host capabilities, which is a broad security surface. The inner daemon needs its own storage (see storage driver notes below). Slightly slower startup while `dockerd` initializes.
+
+**When to use:** Multi-tenant environments where isolation matters more than minimizing the privilege surface, or when automatic cleanup of nested containers is important.
+
+### Option 3: True DinD (targeted capabilities)
+
+A more locked-down alternative to full privileged mode. Instead of granting all capabilities, add only what `dockerd` needs:
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent-dind:latest
+    cap_add:
+      - SYS_ADMIN
+      - NET_ADMIN
+      - MKNOD
+      - SYS_PTRACE
+    security_opt:
+      - seccomp:unconfined
+      - apparmor:unconfined
+    volumes:
+      - superkick-dind-storage:/var/lib/docker
+```
+
+The exact capabilities needed depend on your kernel version, storage driver, and Docker version. `SYS_ADMIN` is the essential one (for mount namespaces); the others handle networking and device creation. If the inner daemon fails to start, check `dockerd` logs for the specific denied operation and add the corresponding capability.
+
+**Pros:** Narrower privilege surface than `privileged: true`. Same isolation and cleanup benefits as full DinD.
+
+**Cons:** More fragile — the required capability set varies across environments. Still requires `SYS_ADMIN`, which is itself a broad capability. `seccomp:unconfined` disables the default seccomp profile.
+
+**When to use:** When you want DinD isolation but your security policy prohibits `privileged: true`.
+
+### Option 4: Sysbox runtime (unprivileged DinD)
+
+[Sysbox](https://github.com/nestybox/sysbox) is a purpose-built container runtime (acquired by Docker Inc. in 2022) that enables Docker-in-Docker without any elevated privileges. It uses Linux user namespaces to ensure the container's root user has zero capabilities on the host.
+
+Sysbox is installed as an alternative OCI runtime on the Docker host. Use the `container_runtime` setting to tell Docker to run agent containers with Sysbox — no privileged mode, no capabilities, no security opt-outs needed:
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent-dind:latest
+    container_runtime: sysbox-runc
+    # No privileged, no cap_add, no security_opt needed
+```
+
+Sysbox must be [installed on the Docker host](https://github.com/nestybox/sysbox#installation). Once installed, the `container_runtime: sysbox-runc` setting routes agent containers through it automatically — no changes to the host daemon's default runtime are required.
+
+**Pros:** No elevated privileges at all. Full DinD isolation. Automatic cleanup. The most secure option for running nested containers.
+
+**Cons:** Requires Sysbox to be installed on the Docker host (not available in all environments). Not supported on all Linux distributions or kernel versions.
+
+**When to use:** Production environments where security is a priority and you control the host runtime configuration.
+
+### Storage driver considerations
+
+When running a Docker daemon inside a container, the inner daemon needs a storage driver for its image and container layers. The default `overlay2` driver works when the outer filesystem also supports it, but **overlay-on-overlay** (nested OverlayFS) can cause performance issues and subtle bugs on some kernels.
+
+Best practices:
+- **Use a volume mount** for `/var/lib/docker` — this gives the inner daemon a direct filesystem (typically ext4 or xfs) instead of nesting overlay on overlay
+- **`vfs` as a fallback** — the `vfs` storage driver works everywhere but copies full layers (no copy-on-write), so it uses more disk and is slower. Set it via `dockerd --storage-driver=vfs` in your entrypoint if you hit overlay issues
+- **tmpfs for ephemeral workloads** — if agents don't need to persist Docker images across runs, mount `/var/lib/docker` as tmpfs for maximum performance
+
+### Comparison
+
+| Approach | Isolation | Cleanup | Security | Setup complexity |
+|----------|-----------|---------|----------|-----------------|
+| Socket passthrough | None — shared daemon | Manual | Agent has full host Docker access | Low |
+| DinD (privileged) | Full | Automatic | `privileged` grants broad host access | Low |
+| DinD (targeted caps) | Full | Automatic | Narrower but still requires `SYS_ADMIN` | Medium |
+| Sysbox | Full | Automatic | No elevated privileges | Medium (host setup) |