Metadata-Version: 2.4
Name: frontrunner-client
Version: 0.1.0a12
Summary: Remote-only client contracts for AI Frontrunner
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: certifi==2026.7.22
Requires-Dist: httpx==0.28.1

# Frontrunner Client

This is the isolated, remote-only foundation for the future customer
`frontrunner` CLI and local stdio bridge.

Distribution version `0.1.0a12` supports Python `>=3.11,<3.13`. Its immutable
`wave4-remote-client-mcp-stdio-v12` contract fingerprint is
`fd19264152e2fd36daadfa9959dcf1064d78cd5f3c26e85c4c1e2f9c11799f4e`.
The standalone `requirements.lock` has SHA-256
`e1a6163e5146830afa1cd71ec95c5009f42f8a5a4dba195fc40cc4ebebdc39f0`
and pins the reviewed direct `certifi==2026.7.22` and `httpx==0.28.1`
requirements plus their transitive graph with artifact hashes and no extras.

The current package provides:

- explicit canonical HTTPS origin and exact Wave 3
  `afc1.<22-character locator>.<43-character secret>` canonical base64url PAT
  configuration;
- canonical capability catalog and invocation request serialization;
- bounded, strict JSON-object response decoding;
- a caller-injected synchronous transport protocol;
- one validated, non-regressing monotonic whole-call acceptance deadline that
  starts before request validation and serialization, passes only its
  decreasing remaining budget into transport, expires at the exact boundary,
  rejects late transport returns and decoded results, and reports invalid or
  regressing clocks through the fixed `clock_failure` transport taxonomy;
- a concrete synchronous HTTPX adapter with a reviewed explicit TLS context,
  environment/proxy/key-log isolation, scoped HTTPX/HTTP Core log suppression, no
  redirects or retries, fresh-client cookie isolation, finite phase timeouts,
  raw streaming bounds, compression rejection, and late cleanup rejection; and
- a deterministic JSON CLI registered only as
  `frontrunner = frontrunner_client.cli:main`, whose only configuration inputs
  are `FRONTRUNNER_API_ORIGIN` and `FRONTRUNNER_ACCESS_TOKEN`; and
- an exact MCP `2025-06-18` stdio translator with newline-delimited bounded
  JSON-RPC, the standard `initialize` / `notifications/initialized` lifecycle,
  deterministic authority-filtered `tools/list`, and remote-only `tools/call`.
  It has no SDK dependency, database path, subprocess supervisor, custom IPC,
  or hosted listener.

The unmounted CLI contract is:

```console
frontrunner capability catalog --json
frontrunner capability invoke evidence.search \
  --major 1 --arguments-json '{"query":"chip supply"}' --json
frontrunner mcp stdio
```

`python -m frontrunner_client` remains an equivalent module invocation. The
root application owns no console command; the separate `frontrunner-admin`
wheel owns the privileged operator command, and the client wheel is the sole
owner of the bare customer command. Fresh-venv tests prove disjoint three-wheel
console and RECORD ownership, representative clean install orders and uninstall
directions, and the upgrade from the sealed `0.1.0a11` predecessor at commit
`b48d59336cba0ff7ce0170a22fd3a47eaaa6cf44` to `0.1.0a12`. That
interoperability proof is not permission
to install the client into the shared application environment: customer use
requires a fresh client-only environment, and co-installation with a historical
root release that still owns bare `frontrunner` is unsupported.

Version `0.1.0a11` added `mcp_stdio.py` but deliberately omitted the MCP
initialization lifecycle; current Codex therefore could not load it as an MCP
server. Version `0.1.0a12` keeps the same seven-module, dependency, console,
HTTPX, and remote API boundaries while replacing that incompatible protocol
shape with the standard `2025-06-18` lifecycle used by the current Codex CLI.

The repository's local, non-executing release validator is artifact
`wave4-client-release-candidate-v2`, fingerprint
`0fcc271af6abdf86325c254d010272f4c4c34d59702cfd0eaaa14d3ebe3661aa`.
It content-addresses the exact wheel, reviewed source modules, lock, metadata,
entry point, and every `RECORD` row. It does not select or upload to a package
index and cannot replace independent registry-download or Python 3.11/3.12
fresh-install evidence.

The A12 live publication/install bundle must satisfy
`wave4-client-publication-receipt-v2`, fingerprint
`d0f18cd62a800e5c74d01e9a489c04d0fbbc052995a2532b52477fa0b8d76118`.
It requires separate index/authorization evidence, upload and independent
download hash equality, non-yanked metadata, and fresh Python 3.11/3.12 install
proof. The historical A11 production receipt
`5c4df75d92aea899df32cf78c11dcd84332fdc09965d5ebe78f1b7d7b59e2621`
records the one `0.1.0a11` wheel published at `2026-08-15T15:23:50Z`, wheel
SHA-256 `289105b2c60f93612dcdab1a5762e9edfa23f05d3a78c69c2e7ba4f85aa8b45b`,
non-yanked metadata, and successful fresh installs on Python 3.11 and 3.12.

The local publication operator consumes the candidate's exact hash-locked
dependency file and runs fresh Python 3.11 and 3.12 local-wheel preflights
before any production PyPI upload. Each preflight verifies the candidate, lock,
runtime graph, console ownership, and module/CLI version surfaces while
explicitly keeping publication and supported installation false. The operator
hashes a separately retained owner-authorization file, binds the exact local
publisher executable, accepts a PyPI token only through `UV_PUBLISH_TOKEN`, and
never records it. Independent production-index downloads and fresh installs
still run after upload and remain the only inputs to the live publication
receipt. GitHub remains only the Git remote. See
[`docs/local-ci-and-publication.md`](../../docs/local-ci-and-publication.md).

This package also has no default endpoint, token argument, config/token file,
stdin or file configuration, local database mode, OAuth flow, hosted
transport, application/provider integration, deployment, or activation. The
stdio command is an unmounted
local translator and is not a customer-ready connection by itself. Later
authorized slices must supply the mounted endpoint and scoped PAT lifecycle,
then complete production evidence for the separately packaged admin release, hosted MCP/OAuth
surfaces, hard end-to-end completion/preemption, supported installation, and
golden live query. The first secret-free pre-activation Codex configuration
recipe and config-only probe live in
[`docs/codex-mcp-setup.md`](../../docs/codex-mcp-setup.md); their parser
acceptance is not a mounted protocol or live-query proof. The current
deadline is an acceptance bound; hard completion and preemption remain false.
Phase timeouts are defense-in-depth, arbitrary synchronous injected transports
and blocking cleanup are not forcibly interrupted, and the package
intentionally contains no process supervisor, worker, local IPC, or
platform-specific lifecycle code. Hard completion/preemption is not claimed.
