volante 0.3.0__tar.gz

volante-0.3.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "volante",
+  "description": "Volante — a cross-provider multi-model AI orchestration engine for Claude Code (MCP server + /volante:run command).",
+  "owner": {
+    "name": "ribato22"
+  },
+  "plugins": [
+    {
+      "name": "volante",
+      "source": "./plugins/volante",
+      "description": "Multi-model AI orchestration: plan a task DAG, route each task to the best capable model. Bundles the Volante MCP server (volante_run) plus a /volante:run command."
+    }
+  ]
+}

volante-0.3.0/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig — consistent formatting across editors (https://editorconfig.org)
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+[*.py]
+indent_size = 4
+
+[*.{json,jsonc,yml,yaml,toml,md,js,css,html}]
+indent_size = 2
+
+[*.md]
+# Preserve hard line breaks in prose docs.
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

volante-0.3.0/.env.example

@@ -0,0 +1,156 @@
+# .env.example — copy to .env and fill in. NEVER commit .env (it is gitignored).
+# Volante reads these at runtime via volante.build_providers_from_env().
+# Configure ONE OR MORE models. Every configured model joins the routing inventory.
+# Baseline priority (planner/synth only): Anthropic > OpenAI-compat > Kimi > Ollama.
+
+# --- Anthropic (AnthropicProvider) -------------------------------------------
+ANTHROPIC_API_KEY=
+# ANTHROPIC_MODEL=claude-opus-4-8
+# ANTHROPIC_MODELS=claude-opus-4-8,claude-sonnet-4-5   # plural wins over singular
+# ANTHROPIC_NAMES=anthropic/opus,anthropic/sonnet      # optional parallel canonical ids
+# ANTHROPIC_STRENGTHS=coding,reasoning,long_context
+# Optional specialized tags raise task_fit so same-tier models rank apart (see README):
+#   code: software_engineering, debugging, instruction_following
+#   research: research, grounding, long_context
+#   write: writing, creativity, instruction_following
+#   analyze: analysis, math, long_context
+# Without any of these AND without a quality profile, task_fit is the same for every
+# model, so Volante gives it zero weight instead of a flat constant.
+# ANTHROPIC_CONTEXT=200000
+# ANTHROPIC_MAX_OUTPUT=8192
+# ANTHROPIC_TOOLS=true
+# ANTHROPIC_COST_IN=0.015
+# ANTHROPIC_COST_OUT=0.075
+# ANTHROPIC_TIER=4
+
+# --- Generic OpenAI-compatible slot (OpenAICompatProvider) --------------------
+# Works with ANY OpenAI-compatible endpoint (Google AI Studio / Gemini, Groq,
+# OpenRouter, DeepSeek, local vLLM, ...) with a correct model_id, pricing and
+# context window. Only BASE_URL + MODEL are required.
+OPENAI_COMPAT_BASE_URL=
+OPENAI_COMPAT_MODEL=
+# OPENAI_COMPAT_KEY=                 # optional; "none" placeholder for keyless local endpoints
+# OPENAI_COMPAT_NAME=vendor/model    # canonical model_id label (default: openai-compat/<model>)
+# OPENAI_COMPAT_CONTEXT=128000       # context window (standard default)
+# OPENAI_COMPAT_MAX_OUTPUT=8192      # max output tokens (standard default)
+# OPENAI_COMPAT_TOOLS=true           # opt in only when endpoint supports function calling
+# OPENAI_COMPAT_STRENGTHS=coding,reasoning
+# OPENAI_COMPAT_COST_IN=0            # USD / 1k input tokens (0 = free-tier; set for paid)
+# OPENAI_COMPAT_COST_OUT=0           # USD / 1k output tokens
+# OPENAI_COMPAT_TIER=3
+#
+# Example — free Google AI Studio Gemini Flash (highest free-tier intelligence):
+#   OPENAI_COMPAT_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
+#   OPENAI_COMPAT_KEY=<ai-studio-key>
+#   OPENAI_COMPAT_MODEL=gemini-flash-latest
+#   OPENAI_COMPAT_NAME=google/gemini-flash
+#
+# Multiple OpenAI-compatible providers at once — add OPENAI_COMPAT_2_*, _3_*, …
+# (contiguous from 2). Each keeps its own model_id / pricing / context (no reused slot).
+# Example — Gemini (plans + synthesizes) + Groq (cheaper -> parallel workers), both free:
+#   OPENAI_COMPAT_COST_OUT=0.01                              # make Gemini "pricier" than Groq
+#   OPENAI_COMPAT_2_BASE_URL=https://api.groq.com/openai/v1
+#   OPENAI_COMPAT_2_KEY=<groq-key>
+#   OPENAI_COMPAT_2_MODEL=llama-3.3-70b-versatile
+#   OPENAI_COMPAT_2_NAME=groq/llama-3.3
+#   OPENAI_COMPAT_2_COST_OUT=0.0006
+
+# --- Moonshot / Kimi (OpenAICompatProvider) ----------------------------------
+MOONSHOT_API_KEY=
+MOONSHOT_BASE_URL=https://api.moonshot.ai/v1
+# MOONSHOT_MODEL=kimi-k2-0711-preview
+# MOONSHOT_MODELS=kimi-k2-0711-preview,kimi-k2-turbo-preview
+# MOONSHOT_NAMES=kimi/k2,kimi/k2-turbo
+# MOONSHOT_STRENGTHS=coding,reasoning
+# MOONSHOT_CONTEXT=128000
+# MOONSHOT_MAX_OUTPUT=4096
+# MOONSHOT_TOOLS=true
+# MOONSHOT_COST_IN=0.0012
+# MOONSHOT_COST_OUT=0.0012
+# MOONSHOT_TIER=3
+
+# --- Ollama, local & free (OpenAICompatProvider) -----------------------------
+# Run `ollama serve` and `ollama pull llama3.2`, then set:
+# OLLAMA_BASE_URL=http://localhost:11434/v1
+# OLLAMA_MODEL=llama3.2
+# OLLAMA_MODELS=qwen2.5-coder:14b,llama3.2
+# OLLAMA_NAMES=ollama/qwen2.5-coder:14b,ollama/llama3.2
+# OLLAMA_API_KEY=ollama
+# OLLAMA_STRENGTHS=coding,reasoning
+# OLLAMA_CONTEXT=8192
+# OLLAMA_MAX_OUTPUT=2048
+# OLLAMA_TOOLS=false
+# OLLAMA_COST_IN=0
+# OLLAMA_COST_OUT=0
+# OLLAMA_TIER=1
+
+# --- Subscription CLI agents (OPT-IN; consume your INTERACTIVE quota) ----------
+# Drives the official headless CLIs you're logged into — no API key. Orchestrating on
+# them DRAWS FROM YOUR INTERACTIVE SUBSCRIPTION QUOTA (not a metered API): a large run —
+# and especially the eval suite — can exhaust the allowance and trigger a mid-run
+# hard-pause. OFF by default and NEVER registered for the eval (include_subscription=False).
+# Requires the CLI installed & logged in AND the *_ENABLED flag below.
+#
+# Claude Code (`claude -p`, subscription/OAuth):
+# CLAUDE_CODE_ENABLED=1
+# CLAUDE_CODE_MODEL=opus                 # wire model (tier 4 default)
+# CLAUDE_CODE_MODELS=opus,sonnet         # plural wins over singular
+# CLAUDE_CODE_TIER=4                     # ModelInfo.tier for the claude-code seed
+# CLAUDE_CODE_SYSTEM_PROMPT_MODE=replace  # replace (default) | append.
+#   "replace" makes `claude -p` a raw completion (the worker/planner persona REPLACES Claude
+#   Code's base system prompt). Live-verified: with "append", opus answers the goal instead
+#   of emitting the planner's strict JSON DAG -> planning fails. Use "append" only if you
+#   deliberately want the task layered on top of Claude Code's own agent behavior.
+# CLAUDE_CODE_TIMEOUT=120                # subprocess timeout (s)
+# CLAUDE_CODE_MAX_OUTPUT=4096            # conservative max output tokens
+#
+# Codex (`codex exec`, ChatGPT subscription; child env scrubs OPENAI/CODEX API keys):
+# CODEX_ENABLED=1
+# CODEX_MODEL=gpt-5-codex                # follows your Codex config if unset
+# CODEX_MODELS=gpt-5-codex,gpt-5-codex-mini
+# CODEX_TIER=3                           # REQUIRED when enabled (no model-name sniffing)
+# CODEX_CONTEXT=256000                   # default when unset (build_codex_model())
+# CODEX_MAX_OUTPUT=4096
+#
+# Per-run subscription-call cap (reroute to a direct/card model when reached):
+# VOLANTE_MAX_SUBSCRIPTION_CALLS=16         # incl. planner preflight/plan/retry/worker/synth
+# VOLANTE_CLI_AGENT_DEPTH=0                # recursion guard (Volante may run INSIDE Claude Code)
+# OPENAI_COMPAT_TIER=3                   # per-slot routing tier (1 small … 4 frontier)
+
+# Optional strict JSON evidence/metadata keyed by canonical model id. Keep both out of git.
+# Scores are 0..1; task keys: code, research, write, analyze.
+# VOLANTE_QUALITY_PROFILES_FILE=/absolute/path/to/quality-profiles.json
+# Use overrides when models in one plural family have different hard capabilities,
+# context/output limits, prices, or tiers. See the JSON schema/example in README.
+# VOLANTE_MODEL_OVERRIDES_FILE=/absolute/path/to/model-overrides.json
+
+# --- Sandbox & tools ---------------------------------------------------------
+# VOLANTE_SANDBOX=docker              # real container isolation for agentic run_python
+#                                   # (--network none, read-only root, cgroup limits).
+# Unset = auto + fail closed: Docker is used when its daemon answers; when it does not,
+# run_python is NOT offered at all (the planner is told it cannot execute code) rather
+# than silently running model-written code with your files and network. To accept that
+# weaker sandbox deliberately, opt in with:
+# VOLANTE_SANDBOX=subprocess          # no isolation: code runs as you, with host access
+#                                   # (legacy name AIORCH_SANDBOX still works as a fallback)
+# VOLANTE_FETCH_ALLOWLIST=example.com,docs.python.org  # enables host-mediated fetch_url
+# VOLANTE_READ_ROOT=/absolute/path/to/trusted/files    # enables root-scoped read_file
+# The hostname allowlist is not an SSRF boundary against DNS rebinding/private resolutions,
+# and READ_ROOT should be a trusted tree without adversarial concurrent symlink changes.
+
+# --- Web UI (webui/; `uv sync --extra ui` then `uv run python -m webui`) ------
+# VOLANTE_UI_HOST=127.0.0.1
+# VOLANTE_UI_PORT=8000
+# VOLANTE_UI_AUTH_TOKEN=             # required before binding beyond loopback
+# VOLANTE_UI_ALLOWED_HOSTS=          # comma-separated Host header allowlist for remote access
+# VOLANTE_UI_MAX_GOAL_CHARS=20000
+# VOLANTE_UI_MAX_CONCURRENT_RUNS=2
+
+# --- Observability (CLI, MCP server, and Web UI) -----------------------------
+# VOLANTE_LOG=info            # raise engine diagnostics to stderr (debug/info/warning/error).
+#                           # Blank/unset = silent. Use this to see MCP activity in VS Code's
+#                           # "Output" pane. Never written to stdout (the MCP/pipe channel).
+# VOLANTE_USAGE_LOG=~/.volante/usage.jsonl   # append one JSON line per run (status, cash vs plan
+#                           # credit, subscription calls, duration, models, truncated goal).
+#                           # This is the ledger behind `volante --usage` and the Web UI "Usage"
+#                           # page, so IDE/MCP runs stay auditable. Set empty to disable.

volante-0.3.0/.gitattributes

@@ -0,0 +1,11 @@
+# Normalize line endings across platforms.
+* text=auto eol=lf
+
+# Keep GitHub Linguist's language stats representative of the engine itself:
+# the internal design docs/plans are large but are documentation, not code.
+*.md            linguist-documentation
+docs/**         linguist-documentation
+uv.lock         linguist-generated=true -diff
+
+# Treat lockfiles/notebooks as generated in diffs.
+*.ipynb         linguist-generated=true

volante-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Describe the bug
+
+A clear, concise description of what the bug is.
+
+## Reproduction
+
+Minimal steps to reproduce the behavior, ideally a `uv run volante "..."` invocation, a
+`demo.py`/library snippet, or a failing `uv run pytest` test.
+
+```bash
+# commands / code here
+```
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened (include the full error output / traceback if any — `volante` itself should
+never print a raw traceback, so if you see one that's part of the bug).
+
+## Environment
+
+- Volante version (`uv run volante --version`):
+- Python version (`python --version`):
+- OS:
+- Provider(s) configured (Anthropic / OpenAI-compat / Kimi / Ollama / Claude Code / Codex — no need
+  to share keys):
+
+## Additional context
+
+Anything else relevant (logs, related issues, whether it reproduces with `FakeProvider` / no
+network).

volante-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question / discuss an idea
+    url: https://github.com/ribato22/volante/discussions
+    about: For open-ended questions or design discussion before filing a bug/feature issue.
+  - name: Report a security vulnerability
+    url: https://github.com/ribato22/volante/security/advisories/new
+    about: Please do NOT open a public issue for security problems — see SECURITY.md.

volante-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement for Volante
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What are you trying to do, and what's missing or awkward today? (Link to the relevant
+[Roadmap](https://github.com/ribato22/volante/blob/main/README.md#roadmap) item if there is one.)
+
+## Proposed solution
+
+Describe the change you'd like. If it touches routing, providers, cost accounting, or the eval
+scorer, please be explicit about the exact guarantee/limitation you expect (see
+[SECURITY.md](https://github.com/ribato22/volante/blob/main/SECURITY.md) for the existing threat model).
+
+## Alternatives considered
+
+Any alternative approaches or workarounds you've considered.
+
+## Additional context
+
+Anything else — related issues, links, sketches of the API/CLI surface.
+
+---
+
+Note: Volante is a **study engine**, not a production framework (see the README's
+[Non-goals](https://github.com/ribato22/volante/blob/main/README.md#non-goals) section) — it
+deliberately avoids adopting orchestration frameworks (LangChain/LiteLLM/CrewAI) internally.

volante-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What & why
+
+<!-- Describe what changed and why. Note any new invariant or limitation this introduces. -->
+
+## Checklist
+
+- [ ] `uv run pytest` is green (zero-network by default; ran `uv run pytest -m integration` too if
+      this touches network/Docker/subscription-provider code)
+- [ ] `uv run ruff check .` is clean
+- [ ] Tests added/updated for the behavior change (see
+      [CONTRIBUTING.md](https://github.com/ribato22/volante/blob/main/CONTRIBUTING.md) — test-driven,
+      small focused changes)
+- [ ] `CHANGELOG.md`'s `[Unreleased]` section is updated (Added/Changed/Fixed, matching existing
+      style)
+- [ ] If this touches isolation/sandboxing or the eval scorer: the exact guarantee and its limits
+      are stated honestly (see
+      [SECURITY.md](https://github.com/ribato22/volante/blob/main/SECURITY.md)) — no overclaiming
+- [ ] README updated if user-facing behavior (CLI flags, env vars, Providers) changed

volante-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege: CI only needs to read the repo contents.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev --locked
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type-check (mypy; enforces the shipped py.typed promise)
+        run: uv run mypy src/volante
+
+      - name: Test (no network; integration tests skipped by default)
+        run: uv run pytest --cov=src/volante --cov=eval --cov-report=term-missing
+
+  build:
+    name: build & package smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check package metadata (twine)
+        run: uvx twine check dist/*
+
+      - name: Wheel-install smoke test
+        # Catches packaging regressions a unit test can't (accidental webui/ or docs/
+        # inclusion, a broken `volante` console-script entrypoint, missing dependency
+        # metadata) by installing the built wheel into a throwaway venv — separate
+        # from the dev environment `uv sync --dev` builds for the test job above.
+        run: |
+          python3 -m venv /tmp/volante-wheel-venv
+          /tmp/volante-wheel-venv/bin/pip install --quiet dist/*.whl
+          /tmp/volante-wheel-venv/bin/volante --version
+          /tmp/volante-wheel-venv/bin/volante --help

volante-0.3.0/.github/workflows/publish-mcp.yml

@@ -0,0 +1,71 @@
+name: Publish to MCP Registry
+
+# Publishes server.json to the official MCP Registry (registry.modelcontextprotocol.io)
+# via GitHub OIDC — no token stored. The `io.github.ribato22/*` namespace is authorized
+# because this workflow runs in ribato22's repo. The release workflow calls this
+# after PyPI and GitHub Release succeed; maintainers can also run it manually.
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: Immutable release ref to publish
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref whose server.json should be published
+        required: true
+        default: main
+        type: string
+
+permissions:
+  id-token: write # OIDC token for MCP Registry auth
+  contents: read
+
+jobs:
+  publish-mcp:
+    name: Publish server.json to the MCP Registry
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Wait for the PyPI release to carry the ownership marker
+        # The registry verifies ownership by finding `mcp-name: <name>` in the PyPI
+        # package description (our README). Ensure the matching version is live first,
+        # so a tag that also triggers the PyPI release doesn't race ahead of it.
+        run: |
+          ver="$(python3 -c "import json;print(json.load(open('server.json'))['version'])")"
+          name="$(python3 -c "import json;print(json.load(open('server.json'))['name'])")"
+          echo "waiting for PyPI volante $ver with marker 'mcp-name: $name'"
+          for i in $(seq 1 40); do
+            desc="$(curl -sf "https://pypi.org/pypi/volante/$ver/json" \
+              | python3 -c "import sys,json;print(json.load(sys.stdin)['info']['description'])" 2>/dev/null || true)"
+            if printf '%s' "$desc" | grep -q "mcp-name: $name"; then
+              echo "marker present on PyPI $ver"; exit 0
+            fi
+            echo "attempt $i/40: not yet; sleeping 20s"; sleep 20
+          done
+          echo "::error::PyPI $ver with the ownership marker was not found in time"; exit 1
+
+      - name: Install mcp-publisher
+        run: |
+          version="1.7.9"
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          expected_sha256="ab128162b0616090b47cf245afe0a23f3ef08936fdce19074f5ba0a4469281ac"
+          url="https://github.com/modelcontextprotocol/registry/releases/download/v${version}/${archive}"
+          curl --fail --location --proto '=https' --tlsv1.2 "$url" --output "$archive"
+          printf '%s  %s\n' "$expected_sha256" "$archive" | sha256sum --check --strict
+          tar --extract --gzip --file "$archive" mcp-publisher
+          chmod 0755 mcp-publisher
+          ./mcp-publisher --version
+
+      - name: Authenticate to the MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+
+      - name: Validate and publish server.json
+        run: |
+          ./mcp-publisher validate server.json
+          ./mcp-publisher publish

volante-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,195 @@
+name: Release
+
+# Tag-triggered publish to PyPI via Trusted Publishing (OIDC) - no API token stored
+# in this repo. NOTE: the publish step only succeeds once a "trusted publisher" for
+# this repo + workflow (release.yml, environment `pypi`) is configured on the PyPI
+# project settings (https://docs.pypi.org/trusted-publishers/). OIDC works whether
+# the GitHub repo is public or private; until that trusted publisher exists, pushing
+# a v* tag builds correctly but the publish step fails at the PyPI end.
+on:
+  push:
+    tags: ["v*"]
+
+# Least privilege at the top level; the publish job opts into id-token below.
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify release candidate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: "3.11"
+          enable-cache: true
+
+      - name: Install development dependencies
+        run: uv sync --dev --locked
+
+      - name: Verify lint, types, tests, and distribution contracts
+        run: |
+          uv run ruff check .
+          uv run mypy src/volante
+          uv run pytest
+
+  build:
+    name: Build release artifacts
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Verify the git tag matches the built version
+        # A mislabeled tag would otherwise publish an immutable, wrongly-versioned
+        # artifact to PyPI. Parse the version straight from the built wheel filename
+        # (volante-<version>-py3-none-any.whl) and require tag `vX.Y.Z` == `X.Y.Z`.
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          wheel="$(ls dist/*.whl | head -n1)"
+          built="$(basename "$wheel" | cut -d- -f2)"
+          echo "tag=$tag built=$built"
+          test "$tag" = "$built" || { echo "::error::tag v$tag != built version $built"; exit 1; }
+
+      - name: Check package metadata (twine)
+        run: uvx twine check dist/*
+
+      - name: Validate and build MCPB
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          npx --yes @anthropic-ai/mcpb@2.1.2 validate mcpb/manifest.json
+          npx --yes @anthropic-ai/mcpb@2.1.2 pack mcpb "volante-${version}.mcpb"
+          test -s "volante-${version}.mcpb"
+
+      - name: Upload Python distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Upload MCPB
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: mcpb
+          path: volante-*.mcpb
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/volante/
+    # Job-scoped: only this job gets the OIDC token used for Trusted Publishing.
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          # Idempotent: re-running a tag (e.g. after a history rewrite) must not fail
+          # on the immutable, already-published version.
+          skip-existing: true
+
+      - name: Verify PyPI actually serves THESE artifacts
+        # skip-existing makes a re-tagged, already-published version succeed silently.
+        # Combined with a forgotten version bump that is indistinguishable from a real
+        # release: the job is green, the GitHub Release is cut, and PyPI still serves the
+        # OLD code. Compare the digests instead of trusting the exit status.
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          version="${VERSION#v}"
+          curl -fsSL "https://pypi.org/pypi/volante/${version}/json" -o pypi.json
+          python - <<'PY'
+          import hashlib, json, os, pathlib, sys
+
+          version = os.environ["VERSION"].removeprefix("v")
+          published = {
+              entry["filename"]: entry["digests"]["sha256"]
+              for entry in json.load(open("pypi.json"))["urls"]
+          }
+          built = sorted(pathlib.Path("dist").iterdir())
+          if not built:
+              sys.exit("::error::no built artifacts to verify")
+          failures = []
+          for path in built:
+              local = hashlib.sha256(path.read_bytes()).hexdigest()
+              remote = published.get(path.name)
+              if remote is None:
+                  failures.append(f"{path.name} is not published on PyPI for {version}")
+              elif remote != local:
+                  failures.append(
+                      f"{path.name}: PyPI serves {remote[:12]}… but this run built "
+                      f"{local[:12]}… — the upload was skipped as already-existing, so "
+                      f"version {version} was NOT actually released from this commit"
+                  )
+          for failure in failures:
+              print(f"::error::{failure}")
+          sys.exit(1 if failures else 0)
+          PY
+
+  github-release:
+    name: Publish GitHub Release
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download Python distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: artifacts/dist
+
+      - name: Download MCPB
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: mcpb
+          path: artifacts
+
+      - name: Create or refresh the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          assets=(artifacts/dist/* "artifacts/volante-${version}.mcpb")
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" "${assets[@]}" --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" "${assets[@]}" \
+              --verify-tag \
+              --title "Volante ${version}" \
+              --generate-notes
+          fi
+
+  publish-mcp:
+    name: Publish MCP Registry record
+    needs: [publish, github-release]
+    permissions:
+      contents: read
+      id-token: write
+    uses: ./.github/workflows/publish-mcp.yml
+    with:
+      ref: ${{ github.ref }}