chore(ai): update tests/AGENTS.md, add pytest-vcr skill and add ENABLE_VERTEX flag for better ergonomics

.agents/README.md

@@ -0,0 +1,16 @@
+# `.agents/` Directory
+
+This directory contains cross-agent project configuration that works with any coding agent (Claude Code, OpenCode, Codex, etc).
+
+## Skills
+
+`.agents/skills/` is the canonical location for project skills. `.claude/skills` is a symlink pointing here for Claude Code compatibility.
+
+### Merge conflict resolution
+
+If you get a `CONFLICT (file/directory)` on `.claude/skills` after a merge, move any new skills to `.agents/skills/` and restore the symlink:
+
+```bash
+rm -rf .claude/skills
+ln -s ../.agents/skills .claude/skills
+```

.agents/skills/pytest-vcr/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: pytest-vcr
+description: Record, rewrite, and debug VCR cassettes for HTTP recordings. Use when running tests with --record-mode, verifying cassette playback, or inspecting request/response bodies in YAML cassettes.
+allowed-tools: Bash(uv run pytest *), Bash(uv run python .agents/skills/pytest-vcr/parse_cassette.py *), Bash(.agents/skills/pytest-vcr/run-vertex-tests.sh *), Bash(source .env && uv run pytest *), Bash(git diff *)
+---
+
+# Pytest VCR Workflow
+
+Use this skill when recording or re-recording VCR cassettes for tests, or when debugging cassette contents.
+
+## Prerequisites
+
+- Verify `.env` exists: `test -f .env && echo 'ok' || echo 'missing'`
+- Missing API keys will cause clear test errors at runtime
+
+## Important flags
+- `--record-mode=rewrite` : Record cassettes (works for both new and existing)
+- `--lf` : Run only the last failed tests
+- `-vv` : Verbose output
+- `--tb=line` : Short traceback output
+- `-k=""` : Run tests matching the given substring expression
+
+## Recording Cassettes
+
+### Step 1: Record cassettes
+
+```bash
+source .env && uv run pytest path/to/test.py::test_function_name -v --tb=line --record-mode=rewrite
+```
+
+Multiple tests can be specified:
+```bash
+source .env && uv run pytest path/to/test.py::test_one path/to/test.py::test_two -v --tb=line --record-mode=rewrite
+```
+
+### Step 2: Verify recordings
+
+Run the same tests WITHOUT `--record-mode` to verify cassettes play back correctly:
+```bash
+source .env && uv run pytest path/to/test.py::test_function_name -vv --tb=line
+```
+
+### Step 3: Review snapshots
+
+If tests use [`snapshot()`](https://github.com/15r10nk/inline-snapshot) assertions:
+- The test run in Step 2 auto-fills snapshot content
+- Review the generated snapshot files to ensure they match expected output
+- You only review - don't manually write snapshot contents
+- Snapshots capture what the test actually produced, additional to explicit assertions
+
+## Parsing Cassettes
+
+Parse VCR cassette YAML files to inspect request/response bodies without dealing with raw YAML.
+
+### Usage
+
+```bash
+uv run python .agents/skills/pytest-vcr/parse_cassette.py <cassette_path> [--interaction N]
+```
+
+### Examples
+
+```bash
+# Parse all interactions in a cassette
+uv run python .agents/skills/pytest-vcr/parse_cassette.py tests/models/cassettes/test_foo/test_bar.yaml
+
+# Parse only interaction 1 (0-indexed)
+uv run python .agents/skills/pytest-vcr/parse_cassette.py tests/models/cassettes/test_foo/test_bar.yaml --interaction 1
+```
+
+### Output
+
+For each interaction, shows:
+- Request: method, URI, parsed body (truncated base64)
+- Response: status code, parsed body (truncated base64)
+
+Base64 strings longer than 100 chars are truncated for readability.
+
+
+## Vertex AI Tests
+
+Vertex tests use the `skip_unless_vertex` fixture from `tests/conftest.py` — they only run in CI or when `ENABLE_VERTEX=1` is set. `ENABLE_VERTEX=1` is only needed when recording/rewriting cassettes locally; during playback, cassettes replay without live auth. Add `skip_unless_vertex: None` as a parameter to any new vertex test.
+
+Vertex auth works two ways:
+- **`GOOGLE_APPLICATION_CREDENTIALS`**: set this env var to a service account JSON path — no gcloud needed
+- **gcloud**: the script auto-detects project and checks auth via `gcloud`
+
+Use the provided script:
+
+```bash
+# Record Vertex cassettes
+.agents/skills/pytest-vcr/run-vertex-tests.sh tests/path/to/test.py -v --tb=line --record-mode=rewrite
+
+# Verify playback
+.agents/skills/pytest-vcr/run-vertex-tests.sh tests/path/to/test.py -vv --tb=line
+```
+
+If using gcloud and auth fails:
+```bash
+gcloud auth application-default login
+gcloud config set project <your-project-id>
+```
+
+## Full Workflow Example
+
+```bash
+# 1. Record cassette
+source .env && uv run pytest tests/models/test_openai.py::test_chat_completion -v --tb=line --record-mode=rewrite
+
+# 2. Verify playback and fill snapshots
+source .env && uv run pytest tests/models/test_openai.py::test_chat_completion -vv --tb=line
+
+# 3. Review test code diffs (excludes cassettes)
+git diff tests/ -- ':!**/cassettes/**'
+
+# 4. List new/changed cassettes (name only - use parse_cassette.py to inspect)
+git diff --name-only tests/ -- '**/cassettes/**'
+
+# 5. Inspect cassette contents if needed
+uv run python .agents/skills/pytest-vcr/parse_cassette.py tests/models/cassettes/test_openai/test_chat_completion.yaml
+```

.agents/skills/pytest-vcr/parse_cassette.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Parse VCR cassette files and pretty-print request/response bodies."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def truncate_base64(obj: object, max_len: int = 100) -> object:
+    """Recursively truncate base64-like strings in nested structures."""
+    if isinstance(obj, str):
+        if len(obj) > max_len and re.match(r'^[A-Za-z0-9+/=]+$', obj[:100]):
+            return f'{obj[:50]}...[truncated {len(obj)} chars]...{obj[-20:]}'
+        if obj.startswith('data:') and len(obj) > max_len:
+            return f'{obj[:80]}...[truncated {len(obj)} chars]'
+        return obj
+    elif isinstance(obj, dict):
+        return {k: truncate_base64(v, max_len) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [truncate_base64(item, max_len) for item in obj]
+    return obj
+
+
+def _extract_body(part: dict[str, object]) -> object | None:
+    """Extract body from a request/response, trying parsed_body first, then standard VCR body.string."""
+    if 'parsed_body' in part:
+        return part['parsed_body']
+    body = part.get('body')
+    if isinstance(body, dict):
+        body_str = body.get('string')
+        if isinstance(body_str, str) and body_str:
+            try:
+                return json.loads(body_str)
+            except json.JSONDecodeError:
+                return body_str
+    elif isinstance(body, str) and body:
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError:
+            return body
+    return None
+
+
+def parse_cassette(path: Path, interaction_idx: int | None = None) -> None:
+    """Parse and print cassette contents."""
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    interactions = data.get('interactions', [])
+    if not interactions:
+        print('No interactions found in cassette')
+        return
+
+    indices = [interaction_idx] if interaction_idx is not None else range(len(interactions))
+
+    for i in indices:
+        if i < 0 or i >= len(interactions):
+            print(f'Interaction {i} not found (only {len(interactions)} interactions)')
+            continue
+
+        interaction = interactions[i]
+        req = interaction.get('request', {})
+        resp = interaction.get('response', {})
+
+        print(f'\n{"="*60}')
+        print(f'INTERACTION {i}')
+        print('='*60)
+
+        print(f'\n--- REQUEST ---')
+        print(f'Method: {req.get("method", "N/A")}')
+        print(f'URI: {req.get("uri", "N/A")}')
+        req_body = _extract_body(req)
+        if req_body is not None:
+            truncated = truncate_base64(req_body)
+            print(f'Body:\n{json.dumps(truncated, indent=2)}')
+
+        print(f'\n--- RESPONSE ---')
+        status = resp.get('status', {})
+        print(f'Status: {status.get("code", "N/A")} {status.get("message", "")}')
+        resp_body = _extract_body(resp)
+        if resp_body is not None:
+            truncated = truncate_base64(resp_body)
+            print(f'Body:\n{json.dumps(truncated, indent=2)}')
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Parse VCR cassette files')
+    parser.add_argument('cassette', type=Path, help='Path to cassette YAML file')
+    parser.add_argument('--interaction', '-i', type=int, help='Specific interaction index (0-based)')
+    args = parser.parse_args()
+
+    if not args.cassette.exists():
+        print(f'File not found: {args.cassette}', file=sys.stderr)
+        sys.exit(1)
+
+    parse_cassette(args.cassette, args.interaction)
+
+
+if __name__ == '__main__':
+    main()

.agents/skills/pytest-vcr/run-bedrock-tests.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Run tests with AWS bedrock profile (assumes bedrock-test-role via ~/.aws/config).
+# Usage: .claude/skills/pytest-vcr/run-bedrock-tests.sh [pytest args...]
+set -e
+
+export AWS_PROFILE=bedrock
+export AWS_DEFAULT_REGION=us-east-1
+unset AWS_BEARER_TOKEN_BEDROCK AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
+
+source .env
+exec uv run pytest "$@"

.agents/skills/pytest-vcr/run-vertex-tests.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Run pytest with Vertex AI auth
+# Usage: .agents/skills/pytest-vcr/run-vertex-tests.sh [pytest args...]
+
+set -e
+
+# Force Vertex auth path (not API key)
+unset GOOGLE_API_KEY GEMINI_API_KEY
+
+if [ -n "$GOOGLE_APPLICATION_CREDENTIALS" ]; then
+    # Service account credentials — no gcloud needed
+    if [ ! -f "$GOOGLE_APPLICATION_CREDENTIALS" ]; then
+        echo "ERROR: GOOGLE_APPLICATION_CREDENTIALS file not found: $GOOGLE_APPLICATION_CREDENTIALS"
+        exit 1
+    fi
+    # Extract project from credentials JSON if not already set
+    if [ -z "$GOOGLE_PROJECT" ] && [ -z "$GOOGLE_CLOUD_PROJECT" ]; then
+        PROJECT=$(python3 -c "import json; print(json.load(open('$GOOGLE_APPLICATION_CREDENTIALS')).get('project_id', ''))" 2>/dev/null)
+        if [ -n "$PROJECT" ]; then
+            export GOOGLE_PROJECT="$PROJECT"
+            export GOOGLE_CLOUD_PROJECT="$PROJECT"
+        fi
+    fi
+else
+    # Fall back to gcloud
+    GCLOUD="$(command -v gcloud 2>/dev/null)"
+    if [ ! -x "$GCLOUD" ]; then
+        echo "ERROR: No GOOGLE_APPLICATION_CREDENTIALS set and gcloud not found."
+        echo "Either set GOOGLE_APPLICATION_CREDENTIALS or install Google Cloud SDK."
+        exit 1
+    fi
+
+    if ! "$GCLOUD" auth application-default print-access-token &>/dev/null; then
+        echo "ERROR: gcloud auth not configured. Run:"
+        echo "  gcloud auth application-default login"
+        exit 1
+    fi
+
+    PROJECT=$("$GCLOUD" config get-value project 2>/dev/null)
+    if [ -z "$PROJECT" ] || [ "$PROJECT" = "(unset)" ]; then
+        echo "ERROR: no gcloud project configured. Run:"
+        echo "  gcloud config set project <your-project-id>"
+        exit 1
+    fi
+
+    export GOOGLE_PROJECT="$PROJECT"
+    export GOOGLE_CLOUD_PROJECT="$PROJECT"
+fi
+
+export GOOGLE_LOCATION="${GOOGLE_LOCATION:-global}"
+
+echo "Vertex AI: project=${GOOGLE_PROJECT:-${GOOGLE_CLOUD_PROJECT:-unset}} location=$GOOGLE_LOCATION"
+
+ENABLE_VERTEX=1 uv run pytest "$@"

.claude/settings.json

@@ -5,6 +5,8 @@
       "Bash(ls:*)",
       "Bash(tree:*)",
       "Bash(grep:*)",
+      "Bash(git -C * diff:*)",
+      "Bash(git -C * log:*)",
       "Bash(git log:*)",
       "Bash(git diff:*)",
       "Bash(git grep:*)",
@@ -19,7 +21,8 @@
       "Bash(gh run view:*)",
       "Bash(gh run list:*)",
       "Bash(uv run:*)",
-      "Bash(make:*)"
+      "Bash(make:*)",
+      "Skill(pytest-vcr:*)"
     ]
   }
 }

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.github/workflows/ci.yml

@@ -23,6 +23,16 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Verify .claude/skills symlink
+        run: |
+          if [ ! -L .claude/skills ]; then
+            echo "ERROR: .claude/skills must be a symlink to ../.agents/skills"
+            echo "Skills live in .agents/skills/. See .agents/README.md"
+            echo "If this happened after a merge conflict, move new skills to .agents/skills/ and run:"
+            echo "  rm -rf .claude/skills && ln -s ../.agents/skills .claude/skills"
+            exit 1
+          fi
+
       - uses: astral-sh/setup-uv@v5
         with:
           python-version: "3.13"

.gitignore

@@ -21,10 +21,12 @@ node_modules/
 /test_tmp/
 .mcp.json
 .claude/*
-!.claude/skills/
-.claude/skills/*
-!.claude/skills/address-feedback
-!.claude/skills/pre-push-review
+!.claude/settings.json
+!.claude/skills
+.agents/skills/*
+!.agents/skills/pytest-vcr/
+!.agents/skills/address-feedback
+!.agents/skills/pre-push-review
 .github/.review-context/
 /.cursor/
 /.devcontainer/

.pre-commit-config.yaml

@@ -67,6 +67,12 @@ repos:
         language: system
         types: [python]
         pass_filenames: false
+      - id: check-skills-symlink
+        name: Check .claude/skills is a symlink
+        entry: test -L .claude/skills
+        language: system
+        always_run: true
+        pass_filenames: false
       - id: check-cassettes
         name: Check cassettes
         entry: uv