# AGENTS.md — Instructions for AI coding agents
## Language & Tooling
- **Language**: Rust, 2021 edition
- **Build**: `cargo build`
- **Test**: `cargo test`
- **Lint**: `cargo clippy --all-targets -- -D warnings`
- **Format**: `cargo fmt`
- **Coverage**: `cargo tarpaulin --out xml`
## Architecture (two operational modes)
`openlatch-provider` is a single binary with two modes:
1. **Management CLI mode** — one-shot subcommands (`login`, `init`, `publish`, `register`, `tools`, `providers`, `bindings`, …). Calls the OpenLatch platform REST API.
2. **Runtime daemon mode** — `openlatch-provider listen [--port 8443]`. Long-running HTTPS server that receives HMAC-signed webhooks from `openlatch-platform`, verifies, proxies events to vendor's localhost-hosted detection tools, returns HMAC-signed verdicts.
Symmetric to `openlatch-client` (the agent-side thin forwarder) but on the supply side.
## Key Constraints
- All wire types are generated from JSON Schemas in `schemas/` via `typify` (build.rs).
- `schemas/` is vendored from `@openlatch/client-schemas`; a CI workflow (`schemas-sync.yml`) keeps it in sync with upstream releases.
- Inbound webhook auth: Standard Webhooks v1 HMAC-SHA256 over raw body bytes, ±5 minute timestamp skew, LRU replay-cache (size 1000, TTL 5 min) on `webhook-id`.
- mTLS deferred to Phase 2.
- rustls only — `openssl-sys` and `native-tls` are forbidden in the dependency graph.
- Token storage: OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service) with plaintext-file fallback for headless Linux.
- HTTP client: `reqwest` with `rustls-tls`. HTTP server (runtime mode): `axum` + `tokio-rustls`.
- Telemetry: see "Telemetry consent model" below.
## Telemetry consent model
Two SEPARATE consent subsystems with deliberately different defaults — disabling one does NOT disable the other (per `.claude/rules/telemetry.md` preamble).
PostHog usage telemetry: **opt-in**. First-run prompt; can be enabled or disabled via `openlatch-provider config set telemetry.enabled <bool>`. Disabled in CI environments and when `DO_NOT_TRACK=1` or `OPENLATCH_TELEMETRY_DISABLED=1`. Baked PostHog key + EU instance, byte-grep-verified at build time. Consent state lives in `~/.openlatch/provider/telemetry.json`; identity is `machine_id` pre-auth and `editor_id` post-auth.
Sentry crash reporting: **default-on**. Captures Rust panic backtraces only — no event payloads, no env-var values, no tokens, no file paths. Opt out via `SENTRY_DISABLED=1` or `[crashreport] enabled = false` in `~/.openlatch/provider/config.toml`. Stack-locals are scrubbed before send.
Rationale for the asymmetry: aggregated panic backtraces have a much lower privacy cost than per-action usage events, and crash signals are critical for security-software trust — a binary that silently crashes once a week is worse than one that emits a stack trace we can fix. PostHog's opt-in stance matches the user-action telemetry industry standard; Sentry's default-on stance matches what every other observability-grade tool (rustup, gh, helm) does for crash reports. Documented in detail at `.claude/rules/telemetry.md`.
## Performance
- Binary size target: ~30 MB; cold start: <500 ms; runtime in-pipeline overhead p95 ≤ 25 ms.
- The `listen` daemon is on the hot path between platform and vendor tool — event processing throughput matters.
## Repository
- Issues / source: https://github.com/OpenLatch/openlatch-provider
- Docs: https://docs.openlatch.ai/provider
- Companion: https://github.com/OpenLatch/openlatch-client