use-agent 1.0.0__tar.gz

use_agent-1.0.0/.github/workflows/deploy.yaml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

use_agent-1.0.0/.github/workflows/testing.yaml

@@ -0,0 +1,36 @@
+name: Testing
+on:
+  push:
+    branches: ["**"]
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+    tags-ignore: ["*"]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run coverage run && uv run coverage report

use_agent-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage
+.coverage.*
+.pytest_cache/
+.ruff_cache/
+
+# Local secrets & private config — NEVER commit
+credentials.json
+token.json
+config.toml
+*.pem
+.env
+.env.*
+!.env.example
+!config.example.toml
+
+justfile

use_agent-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.11
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.25
+    hooks:
+      - id: tombi-format

use_agent-1.0.0/CLAUDE.md

@@ -0,0 +1,221 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`use-agent` is a Claude Agent that triages a Gmail inbox for
+unsolicited sales email and bulk marketing. It replies to cold
+sales pitches in the user's voice and archives them; for bulk
+marketing it honors the RFC 8058 one-click unsubscribe and
+Trashes the thread. It's built on the Claude Agent SDK; Gmail API
+operations are exposed as tools via an in-process SDK MCP server.
+
+Python 3.14, uv, hatchling + hatch-vcs, ruff. Runtime deps:
+`claude-agent-sdk`, `google-api-python-client`,
+`google-auth-oauthlib`, `jinja2`, `rich`.
+
+## Commands
+
+```bash
+uv sync                               # install runtime + dev deps
+uv run use-agent auth                 # one-time Gmail OAuth
+uv run use-agent run --dry-run        # classify only
+uv run use-agent run                  # full run: reply + archive
+uv run use-agent run --daemon --interval 30m --logfile run.log
+uv run use-agent run --json | jq .    # stdout is pure JSON
+
+uv run ruff check .
+uv run ruff format --check .
+uv run coverage run                   # pytest under coverage
+uv run coverage report
+```
+
+`ANTHROPIC_API_KEY` is required for any `run`.
+
+## Architecture
+
+The data flow is deliberately narrow. All user-specific context enters
+through `config.toml`; everything else is derivable from the code.
+
+```
+cli.main → Settings.load() → agent.run(settings, reporter)
+                                 ↓
+                     _render_system_prompt(settings)
+                                 ↓
+                     claude_agent_sdk.query(
+                         prompt=<user-prompt>,
+                         options=ClaudeAgentOptions(
+                             system_prompt=<rendered>,
+                             mcp_servers={'gmail': <built from GmailClient>},
+                             allowed_tools=[mcp__gmail__search, ...],
+                             setting_sources=[],  # hermetic
+                             model=<from config>,
+                         ),
+                     )
+                                 ↓
+                      streaming AssistantMessage/TextBlock
+                                 ↓
+                        reporter.on_text(...)   (→ narration logger)
+                                 ↓
+                        reporter.finish()       (→ stdout: table/JSON)
+```
+
+Key module responsibilities:
+
+- `gmail.GmailClient` is the only module that touches the Gmail REST
+  API. It returns frozen `Message` dataclasses so tool output stays
+  JSON-friendly.
+- `tools.build_mcp_server(client)` wraps six `@claude_agent_sdk.tool`
+  closures (`search`, `get_message`, `reply`, `archive_and_mark_read`,
+  `unsubscribe_and_trash`, `trash`) over a `GmailClient` and returns
+  an SDK MCP server. The closure approach lets the tools share state
+  without a module-global client.
+- The `unsubscribe_and_trash` tool takes the `list_unsubscribe` and
+  `list_unsubscribe_post` header strings as arguments (not just the
+  message_id) so it doesn't re-fetch the message. Headers come from
+  the preceding `get_message` call. The tool chooses between RFC 8058
+  one-click HTTPS POST, HTTPS GET, and mailto based on what the
+  headers expose (see `tools._pick_unsubscribe_action`).
+- `agent.run()` is the orchestration entry point: renders the system
+  prompt, builds the tool server, configures `ClaudeAgentOptions`,
+  streams responses into the `Reporter`, and returns an exit code.
+  Python does no per-message logic — the agent drives the loop.
+- `reporter.Reporter` owns all output. **`on_text` never writes to
+  stdout**; narration goes to the `use_agent.narration` logger
+  instead. `finish()` parses the last ` ```json ` fenced block from
+  the buffered text and renders it as a Rich table (`pretty`),
+  pipe-delimited ASCII (`plain`), or a JSON document (`json`).
+- `settings.Settings` is a frozen dataclass loaded from
+  `config.toml` (path via `USE_AGENT_CONFIG` env var or
+  `~/.config/use-agent/config.toml`). If `[search] query` is omitted,
+  a default `in:inbox is:unread` query is built from the safelist
+  domains as `-from:<domain>` filters.
+
+### Prompts are Jinja2 templates
+
+`use_agent/prompts/classifier.md` and `reply.md` are Jinja2 templates
+rendered at startup. Context injected by `agent._render_context`:
+`user_name`, `organization`, `safelist_domains`, `vendor_names`,
+`voice_guidelines`, `newsletter_keep_domains`,
+`newsletter_keep_list_ids`, `reply_footer`, plus pre-rendered strings
+(`voice_block`, `footer_block`, `footer_instruction`,
+`hard_remove_examples`, etc.). `newsletter_keep_block` is rendered
+separately in `_render_system_prompt` because only the top-level
+system prompt template uses it. The pre-rendered strings exist
+because the repo's pre-commit Markdown formatter strips blank lines
+inside `{% if %}` blocks — avoid Jinja control flow in prompt
+Markdown; pre-render composite blocks in Python and inject them as
+single `{{ ... }}` substitutions.
+
+`reply_footer` is itself a Jinja string (may reference `{{ user_name
+}}` etc.) and is rendered once in `_render_context` before being
+injected into the reply template.
+
+### Editing agent behavior without touching Python
+
+Most behavior tweaks belong in `config.toml` or the prompt Markdown:
+
+- New classification signal → edit `prompts/classifier.md`
+- Change reply voice / add a template → edit `prompts/reply.md`
+- Add a vendor exemption → `[vendors] names` in `config.toml`
+- Add a safelisted domain → `[safelist] domains` in `config.toml`
+- Keep a bulk sender (community list, opted-in newsletter) →
+  `[newsletters] keep_domains` / `keep_list_ids` in `config.toml`
+- Change footer text / disable footer → `[voice] footer` (or `""`)
+- Change model → `[agent] model`
+
+Python changes are only needed when the set of tools, output modes,
+CLI flags, or Gmail operations needs to change.
+
+### Hermetic SDK configuration
+
+`agent.run()` passes `setting_sources=[]`, `settings=None`,
+`skills=None` to `ClaudeAgentOptions` so the agent never merges in
+the developer's `~/.claude/settings.json`, project-level Claude Code
+config, plugins, or auto-discovered skills. The only MCP server the
+agent sees is our Gmail one; the only tools it can call are the four
+in `tools.ALLOWED_TOOLS`. Keep it that way — preserving isolation is
+part of the trust model.
+
+### Threaded replies
+
+Gmail only collapses a reply into the original conversation when all
+three are correct: `In-Reply-To: <original Message-ID>`,
+`References: <chain> <original Message-ID>`, and `threadId` in the
+`users.messages.send` request. `gmail.GmailClient.reply` assembles
+all three from the fetched original. Don't regress this — dropping
+`threadId` or the headers silently demotes replies into new threads.
+
+### Unsubscribing (RFC 2369 / RFC 8058)
+
+`gmail.unsubscribe_targets(list_unsubscribe, list_unsubscribe_post)`
+parses the raw `List-Unsubscribe` header into `{http_urls, mailtos,
+one_click}`. The splitter (`_split_list_unsubscribe`) respects
+angle-bracket nesting because mailto URIs may contain literal
+commas in a `body=` parameter — a plain `split(',')` breaks those.
+
+The `unsubscribe_and_trash` tool calls `_pick_unsubscribe_action`,
+which returns `(method, target)`:
+
+1. `one_click_post` — RFC 8058: POST `List-Unsubscribe=One-Click`
+   as a form body to the HTTPS URI. This is what Gmail and Apple
+   Mail use when the user clicks the native "Unsubscribe" button.
+2. `http_get` — GET the HTTPS URI.
+3. `mailto` — send a standalone (non-threaded) email via
+   `GmailClient.send_unsubscribe_mail` to the address in the
+   mailto URI, using its `subject=` / `body=` parameters.
+4. `none` — no endpoint available; Trash only.
+
+Both the HTTP request (`_http_unsubscribe`) and the mailto send are
+sync-blocking. They run inside the async MCP tool handler, which
+matches the existing googleapiclient pattern throughout `tools.py`.
+The HTTP request has a 10-second timeout (`_UNSUB_HTTP_TIMEOUT`) so
+a stalled endpoint can't hang the whole run.
+
+In-body HTML unsubscribe links are NEVER clicked — clicking
+validates the address to shady senders who already ignored the
+RFC. Messages with no `List-Unsubscribe` header get
+`response_mode=delete` and go straight to Trash.
+
+### Output contract
+
+The agent is prompted to emit exactly one fenced ` ```json ` block
+containing `{"results": [...]}`. The reporter's `_extract_summary`
+walks the buffered text from the end backwards looking for the last
+parseable JSON fence with a `results` array (or a bare list of rows
+with a `classification` key). If the agent forgets to emit the
+block, `finish()` returns exit code 1 — treat this as a real error.
+
+### Logging
+
+| Logger | Level | Purpose |
+|---|---|---|
+| `use_agent.*` | INFO | Notable one-offs (OAuth flow, reply sent); lifecycle (run start, daemon tick, cache stats) is DEBUG |
+| `use_agent.narration` | INFO | Agent's running commentary (buffered text) |
+| `use_agent.tools` | DEBUG | Per-tool-call Gmail operations (search, get, reply, archive, unsubscribe, trash) |
+| `claude_agent_sdk` | WARNING | Pinned; SDK INFO is too chatty |
+
+All handlers write to stderr (plus the `--logfile` target when set)
+so stdout stays pure in `--json` mode.
+
+## Conventions
+
+- **Module-level imports only.** A pre-commit hook rejects `from
+  pathlib import Path` / `from typing import Any` style imports —
+  use `import pathlib` / `import typing`, then `pathlib.Path(...)`,
+  `typing.Any`.
+- Ruff: 79-char lines, single quotes, `py314` target. Config lives
+  in `pyproject.toml`.
+- No compound shell commands: each `Bash` call is one command
+  (repo-wide preference, not project-specific, but still applies).
+- `credentials.json`, `token.json`, and `config.toml` are all
+  gitignored. The repo itself contains no identifying information;
+  `config.example.toml` uses placeholder values only.
+
+## Version
+
+`use_agent.__version__` is read at runtime via
+`importlib.metadata.version('use-agent')`, with a `0.0.0+unknown`
+fallback. `[project] version` is pinned in `pyproject.toml`; hatch-vcs
+is configured but not currently generating a version file.

use_agent-1.0.0/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2026 Gavin M. Roy, AWeber
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+ * Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.