feat(plugins): add extensible client architecture

AGENTS.md

@@ -44,6 +44,7 @@ Read these when working on the relevant area:
 - `agent_docs/debugging.md` — evcxr REPL, binary protocol debugging
 - `agent_docs/binary_size_ci.md` — size-tracking CI: metrics, budgets, baseline semantics
 - `agent_docs/observability.md` — per-session stats (I/O, memory report, TaskInstrument/CPU), design rules
+- `agent_docs/plugin_architecture.md` — native plugin host, lifecycle/capability invariants, future foreign adapter seam
 - `agent_docs/signal_durability.md` — Signal counter leases, pre-wire gates, crash recovery, review checklist
 
 When adding comments to the code, dont be so verbose, also only explain why, not what

Cargo.toml

@@ -9,11 +9,16 @@ repository = "https://github.com/jlucaso1/whatsapp-rust"
 readme = "README.md"
 description = "Rust client for WhatsApp Web"
 
+[package.metadata.docs.rs]
+features = ["plugins"]
+rustdoc-args = ["--cfg", "docsrs"]
+
 [workspace]
 members = [
     ".",
     "examples/voip-cli",
     "http_clients/ureq-client",
+    "plugins/metrics",
     "storages/chat-store",
     "storages/sqlite-storage",
     "tests/bench-integration",
@@ -49,6 +54,9 @@ disallowed_methods = "deny"
 # portable_atomic. Host-only test/bench counters carry an inline allow.
 disallowed_types = "deny"
 
+[workspace.lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(docsrs)"] }
+
 [workspace.dependencies]
 # Shared dependencies
 aes = "0.9.1"
@@ -112,6 +120,12 @@ zlib-rs = { version = "0.6.5", default-features = false, features = ["std", "rus
 
 [features]
 debug-snapshots = ["wacore/debug-snapshots"]
+# Generation-scoped extension lifecycle. Kept opt-in so ordinary clients do not
+# retain lifecycle state or branches when no extension host is present.
+client-lifecycle = []
+# Build-time native plugin host. Kept opt-in so clients that do not use plugins
+# retain the pre-host binary footprint.
+plugins = ["client-lifecycle", "dep:bon"]
 # Optional observability. Off by default: no `tracing` dep, zero overhead.
 # Emits tracing spans/events only; the application installs the subscriber
 # (and any OpenTelemetry bridge). See examples/observability.rs.
@@ -170,6 +184,7 @@ async-trait = { workspace = true }
 base64 = { workspace = true }
 buffa = { workspace = true }
 bytes = { workspace = true }
+bon = { workspace = true, optional = true }
 chrono = { workspace = true, features = ["clock"] }
 event-listener = { workspace = true }
 futures = { workspace = true, features = ["std"] }

README.md

@@ -22,6 +22,7 @@ A high-performance, async Rust library for the WhatsApp Web API. Inspired by [wh
 - **Profile** — Set push name, status text, profile picture
 - **Privacy** — Fetch/set privacy settings, disappearing messages
 - **Modular** — Pluggable storage, transport, HTTP client, and async runtime; SQLite, Tokio WebSocket, and ureq ship as the defaults, swap any of them with `default-features = false`
+- **Native plugins** — Build-time, type-safe extensions with scoped capabilities and lifecycle ownership behind the `plugins` feature
 - **Runtime agnostic** — Bring your own async runtime via the `Runtime` trait (Tokio included by default)
 
 For the full API reference and guides, see the **[documentation](https://whatsapp-rust.jlucaso.com)**.
@@ -60,6 +61,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 The default cargo features wire up the Tokio WebSocket transport, the ureq HTTP client, the SQLite store, and the Tokio runtime; only the storage backend has to be chosen explicitly. Every piece is replaceable through the builder (`with_transport_factory`, `with_http_client`, `with_runtime`) for custom environments such as wasm or embedded targets.
 
+Native plugin APIs are opt-in: use `features = ["plugins"]` when implementing a
+plugin in the application. Published plugin crates can enable that feature in
+their own `whatsapp-rust` dependency, and Cargo feature unification activates it
+for the consumer. See [`agent_docs/plugin_architecture.md`](agent_docs/plugin_architecture.md)
+for the host contract and type-safe API example.
+
 ### One dependency is enough
 
 `whatsapp-rust` re-exports the whole stack, so you never need to declare the sibling crates (`wacore`, `wacore-binary`, `waproto`, `whatsapp-rust-tokio-transport`, `whatsapp-rust-ureq-http-client`, `whatsapp-rust-sqlite-storage`) yourself, including when pinning a git revision:

agent_docs/observability.md

@@ -58,10 +58,30 @@ figures come from the `wacore::stats::HeapSize` trait:
 Semantics: honest estimates for attribution and leak detection, not
 byte-exact accounting. The e2e `memory_soak.rs` logs the byte totals next to
 RSS; its growth-bound assertions are on entry counts.
-When a new cache is added to `Client`, add it to `memory_report()` (the
-`MemoryReport::collections()` list keeps the total and `Display` in sync) and
-— if it can dominate memory — implement `HeapSize` for its value type next to
-that type's definition.
+When a new cache is added to `Client`, add it to `memory_report()` (the common
+`MemoryReport::collections()` list or its feature-gated report section) and —
+if it can dominate memory — implement `HeapSize` for its value type next to that
+type's definition.
+
+With the opt-in `plugins` feature, the report also includes installed plugins,
+active install/connection tasks, retained connection generations, core-event
+subscriptions, custom-event endpoints, and unique queued payload bytes. Fanout
+shares one envelope, so queued payload memory is counted once even when several
+endpoints retain it.
+
+### Plugin host snapshots (opt-in)
+
+`Client::plugin_stats()` is computed only when called and returns lifecycle,
+health, task, subscription, and custom-event counters keyed by public manifest
+ID. `PluginEventRouter::stats()` provides endpoint capacity, current unique
+queue retention, and cumulative delivery/backpressure totals; publishers can
+read their own totals through `PluginEvents::stats()`.
+
+Health is sticky for the lifetime of the host: lifecycle errors/panics,
+timeouts, spawned-task panics, task-drain timeouts, isolated core-event panics,
+resource teardown panics, publication failures, and queue drops mark only the
+responsible plugin as degraded. Concurrent snapshots are intentionally
+approximate, and carry no message content, JIDs, or phone numbers.
 
 ### 3. `BotBuilder::with_task_instrument` — CPU / custom attribution (opt-in)