airut 0.8.0__tar.gz

airut-0.8.0/.airut/README.md

@@ -0,0 +1,81 @@
+# Airut Repo Configuration
+
+This directory contains repo-specific Airut configuration. Files here are read
+from the git mirror's default branch at task start, so changes take effect after
+merging to main without server restart.
+
+For a minimal working example of `.airut/` configuration, see the
+[airut.org website repository](https://github.com/airutorg/website).
+
+## Files
+
+### `airut.yaml` — Repo Config
+
+Controls repo-specific behavior:
+
+```yaml
+default_model: opus         # Claude model when not specified via subaddressing
+timeout: 6000               # Max container execution time (seconds)
+
+network:
+  sandbox_enabled: true     # Enable network allowlist enforcement
+
+container_env:              # Environment variables for containers
+  GH_TOKEN: !secret GH_TOKEN              # Required secret from server pool
+  API_KEY: !secret? API_KEY               # Optional secret (skip if missing)
+  BUCKET_NAME: "my-bucket"                # Inline value (non-secret)
+```
+
+**YAML Tags:**
+
+- `!secret NAME` — resolve from server's secrets pool (error if missing)
+- `!secret? NAME` — optional secret (skip entry if missing)
+- `!env` is NOT allowed in repo config (security: prevents reading server env)
+
+### `network-allowlist.yaml` — Network Sandbox
+
+Defines which hosts containers can access. All HTTP(S) traffic is proxied and
+checked against this allowlist. See `doc/network-sandbox.md`.
+
+```yaml
+# Full-domain entries: all paths and methods allowed
+domains:
+  - api.anthropic.com
+  - pypi.org
+
+# URL prefix entries: host + path required, optional method filter
+url_prefixes:
+  - host: api.github.com
+    path: /repos/owner/repo*
+  - host: api.github.com
+    path: /graphql
+    methods: [POST]              # optional: restrict to specific HTTP methods
+```
+
+**Self-service workflow:** When the agent encounters a blocked request, it can
+edit this file and submit a PR. A human must review and merge before the change
+takes effect.
+
+### `container/Dockerfile` — Container Image
+
+Repo-defined base image. Controls what tools and dependencies are available in
+the Claude Code container. See `spec/image.md`.
+
+The server adds an overlay with the entrypoint script, so the repo Dockerfile
+doesn't need to define `ENTRYPOINT`.
+
+## Server Config
+
+Server-side configuration lives in `config/airut.yaml` (not in this directory).
+It handles:
+
+- Mail server credentials (IMAP/SMTP) — **each repo needs a dedicated inbox**
+- Authorized senders and trusted authserv_id
+- Storage directory and git repo URL
+- Secrets pool (values that `!secret` tags reference)
+
+> **Note:** Airut treats the IMAP inbox as a work queue. It polls for messages,
+> processes every email, and permanently deletes messages after processing.
+> Never use a shared or personal email account.
+
+See `spec/repo-config.md` for the full schema.

airut-0.8.0/.airut/airut.yaml

@@ -0,0 +1,39 @@
+# Repo-specific Airut configuration.
+#
+# Loaded from the git mirror (main branch) at the start of each task.
+# Changes take effect after merge to main without server restart.
+#
+# Tags:
+#   !secret NAME   - Inject a value from the server's secrets pool.
+#                    Errors if the server doesn't export that name.
+#   !secret? NAME  - Optional secret. Skip the entry if the server doesn't
+#                    export that name (no error).
+#   !env is NOT allowed (cannot read server environment variables).
+
+# Default Claude model when the sender does not specify one via
+# subaddressing (e.g. airut+opus@example.com).
+default_model: opus
+
+# Maximum time in seconds a Claude container may run before being killed.
+timeout: 6000
+
+network:
+  # Enable the network sandbox (default: true).
+  # When enabled, containers are placed on an isolated network and all HTTP(S)
+  # traffic is routed through a proxy that enforces the network allowlist
+  # (see .airut/network-allowlist.yaml). Set to false for unrestricted
+  # network access (break-glass override).
+  sandbox_enabled: true
+
+# Environment variables passed into every Claude Code container.
+# Values can be inline strings or !secret references to the server pool.
+# All resolved values are automatically redacted from service logs.
+# Entries whose value resolves to empty are skipped.
+container_env:
+  # Claude authentication (optional; OAuth token takes precedence if both set).
+  # Use !secret? so either or both can be absent from server config.
+  CLAUDE_CODE_OAUTH_TOKEN: !secret? CLAUDE_CODE_OAUTH_TOKEN
+  ANTHROPIC_API_KEY: !secret? ANTHROPIC_API_KEY
+
+  # GitHub token for git operations inside the container.
+  GH_TOKEN: !secret GH_TOKEN

airut-0.8.0/.airut/container/Dockerfile

@@ -0,0 +1,49 @@
+FROM ubuntu:24.04
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    ca-certificates \
+    ripgrep \
+    librsvg2-bin \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+    | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+    | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y gh
+
+# Install Claude Code
+# NOTE: Run from a temp directory to work around OOM bug in installer when run
+# as root during container build (https://github.com/anthropics/claude-code/issues/22536)
+RUN mkdir /tmp/claude-install && cd /tmp/claude-install \
+    && curl -fsSL https://claude.ai/install.sh | bash \
+    && rm -rf /tmp/claude-install
+
+# Add ~/.local/bin to PATH — Airut requires `claude` to be in PATH
+# (also needed for `uv` below)
+ENV PATH="/root/.local/bin:$PATH"
+
+# Install uv (to ~/.local/bin)
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# /workspace is a host mount (ext4) while the uv cache lives on the container
+# overlay filesystem.  Hardlinks cannot cross filesystem boundaries, so uv
+# falls back to copies and prints a noisy warning on every invocation.
+# Setting COPY mode up-front silences the warning.
+ENV UV_LINK_MODE=copy
+
+# Install Python 3.13 via uv
+RUN uv python install 3.13
+
+# Configure git with gh credential helper
+# NOTE: Using COPY instead of heredoc because Podman's image builder
+# incorrectly interprets lines starting with '[' as Dockerfile instructions
+COPY gitconfig /root/.gitconfig
+
+WORKDIR /workspace

airut-0.8.0/.airut/container/gitconfig

@@ -0,0 +1,9 @@
+[credential "https://github.com"]
+	helper =
+	helper = !/usr/bin/gh auth git-credential
+[credential "https://gist.github.com"]
+	helper =
+	helper = !/usr/bin/gh auth git-credential
+[user]
+	name = Airut
+	email = airut@airut.org

airut-0.8.0/.airut/network-allowlist.yaml

@@ -0,0 +1,59 @@
+# Network allowlist for Claude Code containers.
+#
+# Only hosts listed here are reachable from inside the container.
+# All other traffic is blocked by the mitmproxy-based network proxy.
+#
+# To request access to a new host, add it here and submit a PR.
+# See doc/network-sandbox.md for details.
+#
+# This file is read from the git mirror (main branch), not from the
+# conversation workspace.  Changes take effect after merging to main.
+#
+# Pattern matching uses fnmatch-style wildcards (* and ?):
+#   - "*.github.com" matches "api.github.com" but NOT "github.com"
+#   - "/api/*" matches "/api/foo" but NOT "/api"
+#   - "/api" matches only "/api" exactly (no implicit prefix matching)
+
+# Domains: all paths and methods allowed (exact match unless wildcards used)
+domains:
+  - api.anthropic.com
+
+# URL patterns: domain + path pattern required (fnmatch wildcards supported)
+url_prefixes:
+  # Claude telemetry and error reporting (POST-only)
+  - host: statsig.anthropic.com
+    path: ""
+    methods: [POST]
+  - host: sentry.io
+    path: ""
+    methods: [POST]
+
+  # Python packages — read-only (uv sync in entrypoint)
+  - host: pypi.org
+    path: ""
+    methods: [GET, HEAD]
+  - host: files.pythonhosted.org
+    path: ""
+    methods: [GET, HEAD]
+
+  # GitHub — restricted to airut repositories
+  - host: github.com
+    path: /airutorg/airut*
+    methods: [GET, HEAD, POST]
+  - host: api.github.com
+    path: /repos/airutorg/airut*
+  - host: api.github.com
+    path: /graphql
+    methods: [POST]
+  - host: uploads.github.com
+    path: /repos/airutorg/airut*
+    methods: [POST]
+  - host: raw.githubusercontent.com
+    path: /airutorg/airut*
+    methods: [GET, HEAD]
+  - host: objects.githubusercontent.com
+    path: /airutorg/airut*
+    methods: [GET, HEAD]
+  - host: results-receiver.actions.githubusercontent.com
+    path: /rest/runs*
+    methods: [POST]

airut-0.8.0/.claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "attribution": {"commit": "", "pr": ""},
+  "includeCoAuthoredBy": false
+}

airut-0.8.0/.github/workflows/code.yml

@@ -0,0 +1,35 @@
+name: Code Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  code-quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.13
+      - run: uv sync
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run ty check .
+      - name: Markdown format check
+        run: uv run python scripts/check_markdown.py
+      - name: Test coverage
+        run: uv run pytest -n auto --cov=lib --cov-fail-under=100
+      - name: Worktree clean check
+        run: |
+          if [[ -n $(git status --porcelain) ]]; then
+            echo "ERROR: Uncommitted changes after formatting"
+            git status
+            exit 1
+          fi

airut-0.8.0/.github/workflows/e2e.yml

@@ -0,0 +1,26 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  e2e-email-gateway:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.13
+      - run: uv sync
+
+      - name: Run email gateway integration tests
+        run: |
+          uv run pytest tests/integration/ -n auto -v -x \
+            -W error::pytest.PytestUnraisableExceptionWarning \
+            -W error::RuntimeWarning \
+            --allow-hosts=127.0.0.1,localhost

airut-0.8.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for git describe
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.13
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Required for Trusted Publisher
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

airut-0.8.0/.github/workflows/security.yml

@@ -0,0 +1,22 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.13
+      - run: uv sync
+      - name: License check
+        run: uv run pip-licenses
+      - name: Vulnerability scan
+        run: uv run uv-secure uv.lock

airut-0.8.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+.env
+.update.lock
+.gitconfig
+lib/_version.py
+/config/airut.yaml

airut-0.8.0/.mdformat.toml

@@ -0,0 +1,4 @@
+wrap = 80
+number = true
+
+exclude = [".venv/**", ".pytest_cache/**"]