feat: wire-protocol module + first-party Python client

[drewstone]

Summary

Adds a wire-protocol layer (src/wire/) so non-TypeScript clients can drive agent-eval over HTTP or stdio RPC, plus a first-party Python client at clients/python/ that publishes as tangle-agent-eval to PyPI version-locked to the npm package. The TypeScript runtime stays the single source of truth — clients in other languages are transport adapters, not ports.

Architecture

your code (any language)
        │
        ▼
   thin transport client  ──HTTP──▶  agent-eval serve   ──┐
        │                                                  │
        └─────subprocess────────▶  agent-eval rpc        ──┤
                                                           ▼
                                              same TS handlers, same rubrics,
                                              same scoring code

• Schemas (Zod, src/wire/schemas.ts) are the contract.
• Handlers (src/wire/handlers.ts) are pure functions; both transports route to them.
• OpenAPI is auto-emitted from the schemas (pnpm openapi).
• CLI binary (agent-eval): serve | rpc | rpc-batch | openapi | version.
• Python client mirrors the schemas as pydantic v2 models, validates client-side, and falls back from HTTP → subprocess.

What's exposed today

judge, listRubrics, version, /healthz, /openapi.json. One built-in rubric: anti-slop (voice/signal quality for technical-buyer audiences). Inline rubrics also supported on /v1/judge.

Adding a method is mechanical (~6 small edits) — recipe in docs/wire-protocol.md.

Docs overhaul

Drew's directive: SKILL.md was overloaded as the only onboarding doc, dense by design (footgun bible). Split the audiences:

• README.md — human entry point. What it is, who it's for, two quickstarts (wire-protocol + in-process TS).
• docs/concepts.md (new) — 5-min mental model. Vocabulary table, three-layer eval, rubrics, verifiers, traces.
• docs/wire-protocol.md (new) — full HTTP/RPC reference with copy-pasteable input/output for every endpoint. Adding-a-method recipe.
• SKILL.md — same agent directives, but with a vocabulary section at the top so every term used is defined in plain English.
• CLAUDE.md — split-audience pointer.

Principle applied throughout: every term defined in plain English with one example. Every endpoint has copy-pasteable I/O. No jargon undefined.

CI

Dual-publish workflow (.github/workflows/publish.yml):

• verify typechecks JS, runs JS tests, builds, emits OpenAPI, version-locks npm vs PyPI, installs the Python client, runs its tests (including real subprocess integration against dist/cli.js), uploads artifacts.
• publish-npm depends on verify.
• publish-pypi depends on publish-npm. If anything breaks, neither package ships. Versions stay locked.

PyPI uses trusted publishing (OIDC); npm uses NPM_TOKEN.

Tests

• 24 new TS tests in tests/wire/ (schemas, server, rpc).
• 11 Python tests in clients/python/tests/ — including 4 real subprocess integration tests against the bundled CLI (no mocks).
• Existing 576 tests still pass.

Not in this PR (queued for follow-on)

• Wire-surface expansion (runScenario, runBuilderSession, listJudges) — pending shape review of the judge endpoint.
• Switch to datamodel-code-generator for Python models when the surface grows past ~10 endpoints.
• Live LLM integration test gated by AGENT_EVAL_LIVE=1.
• Other-language clients (Rust, Go) — generate from dist/openapi.json when the demand shows up.

Test plan

• Review the wire-protocol shape (src/wire/schemas.ts) — once landed, breaking changes bump WIRE_VERSION.
• Confirm anti-slop rubric weights and failure modes match the autoresearch-loop intent.
• CI: verify job passes including the Python integration tests.
• Local: pnpm build && node dist/cli.js serve then pip install -e clients/python && python -c "from tangle_agent_eval import Client; print(Client().version().version)".
• Local: echo '{}' | node dist/cli.js rpc listRubrics | jq returns the anti-slop rubric.