logos-co · retraca · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 12, 2026
diff --git a/solutions/LP-0008.md b/solutions/LP-0008.md
@@ -0,0 +1,129 @@
+# Solution: LP-0008 — Autonomous AI Agent Module for Logos Core
+
+**Submitted by:** retraca
+
+## Summary
+
+Two Logos Core modules that wire a shielded LEZ wallet, Logos Messaging, Logos Storage, and LEZ programs into a single autonomous agent runtime:
+
+**`lez_wallet_module`** -- a new Qt universal module exposing the LEZ shielded wallet and LEZ program interface via `LogosAPI`. Backed by `lez-wallet-core`, a Rust crate that links against `nssa`, `bedrock_client`, and `wallet` from `lez-build` via FFI. Builds with `--features lez-bridge`; the FFI header is generated by cbindgen and committed.
+
+**`agent_module`** -- a pure C++ Qt universal module implementing the agent runtime: skill dispatcher, spending-threshold gate, A2A-compatible agent card publication and task lifecycle, owner channel over Logos Messaging, and a pluggable inference adapter interface.
+
+## Repository
+
+- **Repo:** https://github.com/retraca/lp-0008-logos-agent-module
+
+## Approach
+
+### Account model
+
+On first deploy, `lez ensure-account` generates a BIP39 mnemonic, derives an NSK (NullifierSecretKey), and persists it encrypted under the owner passphrase in `keystore.json`. The NPK (NullifierPublicKey) is the agent's shielded on-chain identity and is published in its A2A Agent Card. The owner's machine never holds the live NSK at rest.
+
+### lez_wallet_module
+
+The Rust core (`lez-wallet-core/src/provider.rs`) implements eight operations:
+
+- `ensure_account` / `get_npk`: keystore create-or-open; returns `AccountId` and NPK hex.
+- `get_balance` / `get_history` / `sync_private`: read the sequencer at `http://127.0.0.1:3040` (overridable via `wallet_config.json`).
+- `send`: shielded transfer as `NSSATransaction::Private`.
+- `program_call`: fetches account nonces, builds a `PublicTransaction`, signs with `WitnessSet::for_message`, submits as `NSSATransaction::Public`.
+- `program_deploy`: reads the binary, derives `ProgramId` via `Program::new(bytecode)?.id()`, submits as `NSSATransaction::ProgramDeployment`, returns hex program ID.
+
+The C++ Qt module (`qt-module/`) wraps these via cbindgen FFI, exposes them as `StdLogosResult`-returning wire methods, and fires `tx_settled` / `tx_failed` events via `LogosAPI`.
+
+### agent_module
+
+The C++ module (`scaffold/`) dispatches the full skill surface declared in `interfaces/skill.h`. Third parties implement `ISkill` and call `agent_module.register_skill()` -- no core modification needed.
+
+Spending gate: every `wallet.send`, `program.call`, and `program.deploy` call checks `per_tx_limit` and a rolling `per_period_limit`. Calls above threshold go into a pending queue; the agent notifies the owner via the owner chat channel and waits for `approve_pending`. On timeout, the call is rejected and the failure is reported.
+
+A2A layer: `agent.card()` returns a JSON document following the A2A Agent Card schema, including `skills`, `url` (Logos Delivery topic), and an `x-lez-identity.npk` extension field. Cards are published to a named Delivery topic. `agent.task()` drives the A2A task lifecycle: `working` on acceptance, `input-required` if the agent needs more data, `completed` or `failed` on resolution; LEZ payment is transferred on task acceptance.
+
+### CLI
+
+`lez-agent-cli` is a thin Rust binary wrapping the FFI layer. Every subcommand outputs JSON and exits non-zero on error:
+
+```
+lez ensure-account --home <dir> --passphrase <pass>
+lez npk            --home <dir> --passphrase <pass>
+lez balance        --home <dir> --passphrase <pass>
+lez send           --home <dir> --passphrase <pass> --to <addr> --amount <dec>
+lez sync           --home <dir>
+lez history        --home <dir> --passphrase <pass> [--limit N]
+lez program deploy --home <dir> --passphrase <pass> --binary <path>
+lez program call   --home <dir> --passphrase <pass> --program-id <hex> \
+                   --instruction <name> --params <json>
+lez program query  --program-id <hex> --params <json>
+```
+
+## Success Criteria Checklist
+
+- [x] **Agent module loads inside Logos Core** alongside wallet, storage, and messaging modules without modifying those modules. Pre-built arm64 bundles committed at `lez-wallet-module/qt-module/liblez_wallet_module_plugin.so` and `scaffold/libagent_module_plugin.so`. Build steps in `docs/DEPLOYMENT.md`.
+- [x] **Agent has its own shielded LEZ account.** `ensure_account` creates and persists the NSK-encrypted keystore; `npk` exposes the NPK.
+- [x] **Single CLI command to deploy and configure.** `lez ensure-account` + `logoscore -D -m liblez_wallet_module_plugin.so -m libagent_module_plugin.so`. Full steps in `docs/DEPLOYMENT.md`.
+- [x] **Owner interacts via Logos Messaging.** Owner channel uses a `chat_module` E2E conversation. Agent Card publishes the NPK and Delivery topic address.
+- [x] **Spending threshold enforced.** `per_tx_limit` / `per_period_limit` / `period_seconds` configurable via `meta.configure`. Above-threshold calls queue, owner is notified, must call `approve_pending` before the transaction submits.
+- [x] **All default skills implemented.** Storage (upload / download / list / share), Messaging (send / join / create_group), Blockchain (wallet.balance / send / history, program.query / call / deploy), A2A (card / discover / task / subscribe / cancel), Meta (skills / status / configure), plus approve_pending / reject_pending.
+- [x] **A2A-compatible agent-to-agent coordination.** Agent Cards follow the A2A schema. Task lifecycle (working / input-required / completed / failed) runs over Logos Delivery topics. LEZ payment on task acceptance fills the A2A payment gap.
+- [x] **Two agents discover, task, and pay each other.** `agent.discover()` fetches cards from a named Delivery topic. `agent.task()` sends the request, follows the lifecycle, and pays the declared LEZ price. Demonstrated in `demo.sh` steps 5-7.
+- [x] **Three illustrative use cases demonstrated.** Personal file vault, agent services marketplace, privacy-preserving notary. See `ARCHITECTURE.md` and `demo.sh`.
+- [x] **Three agents deployed.** `storage-agent`, `messaging-agent`, `blockchain-agent`, each with a separate home directory and NPK. Deployment steps in `docs/DEPLOYMENT.md` and `demo.sh`.
+- [x] **Full documentation.** `docs/DEPLOYMENT.md`, `ARCHITECTURE.md`, `LEARNING.md`, `README.md`, skill interface at `interfaces/skill.h`.
+- [x] **Documented skill interface.** `interfaces/skill.h` defines `ISkill`; `interfaces/lez_wallet.h` defines `ILezWallet`. Registration via `agent_module.register_skill()`.
+- [x] **Owner-facing interface via Logos app.** Owner sends commands via a `chat_module` E2E conversation (Logos Basecamp). Build instructions in `docs/DEPLOYMENT.md`.
+- [x] **Agent recovers from transient failures.** Wallet sync retries on `reqwest` connection error. Pending approvals survive in-memory across reconnects with a configurable `approval_timeout_seconds`. On timeout, the call is rejected and reported.
+- [x] **Above-threshold transactions not executed without approval.** Spending gate holds calls in `pending_queue`; owner notification and timeout/rejection path documented in `ARCHITECTURE.md`.
+- [x] **Skill failures isolated.** Each skill dispatch is wrapped in a top-level try/catch; a failing skill returns `{"error": "..."}` and does not crash the module or interrupt concurrent skills.
+- [x] **CU costs documented.** See Performance section.
+- [x] **Integration tests against a local sequencer.** `lez-wallet-module/lez-wallet-core/tests/integration_test.rs` -- 7 tests covering account creation, idempotency, NPK round-trip, balance, sync, history, and wrong-passphrase rejection. Run with `cargo test --features lez-bridge --test integration_test -- --include-ignored`.
+- [x] **CI on main branch.** `.github/workflows/ci.yml` -- `rust-unit` (no chain) and `rust-lez-bridge-check` (compile gate) run on every push; `integration` job wires `docker-compose up` for the full suite.
+- [x] **README documents end-to-end usage.** `README.md` + `docs/DEPLOYMENT.md`.
+- [x] **Reproducible demo script.** `demo.sh` runs against a real local sequencer. Invoke as `LEZ=./target/release/lez bash demo.sh`.
+
+## FURPS Self-Assessment
+
+### Functionality
+
+All 15 default skills are implemented across the four categories (Storage 4, Messaging 3, Blockchain 5, A2A 5) plus Meta (skills / status / configure) and approval (approve_pending / reject_pending).
+
+The spending threshold covers `wallet.send`, `program.call`, and `program.deploy`. A2A Agent Cards include the `x-lez-identity.npk` extension field and follow the published schema. Task lifecycle (working / input-required / completed / failed) runs over Logos Delivery topics.
+
+One known gap: the `storage_module`, `chat_module`, and `delivery_module` calls inside `agent_module` are wired to the generated `logos_sdk.h` interface and compile; live messaging and storage require a running Logos Core daemon with those modules loaded. The demo script covers the wallet, program, and A2A paths. Full messaging and storage end-to-end requires `logoscore -D` with all four modules loaded.
+
+### Usability
+
+Two commands to start: `lez ensure-account` to create the agent's shielded identity, then `logoscore -D -m liblez_wallet_module_plugin.so -m libagent_module_plugin.so`. Configuration runs through `meta.configure` from the owner's `logoscore` instance or any Logos app. Pre-built arm64 bundles are committed so macOS arm64 users skip the build entirely.
+
+### Reliability
+
+Wallet sync retries on `reqwest` connection errors. Pending approvals are held with a configurable timeout; on expiry the call is rejected and the owner is notified via the owner channel. Skill dispatch is wrapped per-skill; an exception returns a JSON error and does not terminate the module or affect other running skills.
+
+### Performance
+
+Indicative CU costs on LEZ devnet with `RISC0_DEV_MODE=0`:
+
+| Operation | CU cost (approx.) |
+|---|---|
+| `wallet.send` (shielded transfer) | ~50,000 |
+| `program.call` | ~30,000-80,000 depending on program |
+| `program.deploy` | ~100,000 |
+| `wallet.balance`, `program.query` | 0 (read-only RPC, no proof) |
+
+LEZ's per-transaction compute budget is under active development during testnet; these figures are indicative.
+
+### Supportability
+
+Seven integration tests in `lez-wallet-module/lez-wallet-core/tests/integration_test.rs` cover the full wallet lifecycle. CI runs `rust-unit` and `rust-lez-bridge-check` on every push without a chain; the `integration` job brings up the chain via `docker-compose`. `ARCHITECTURE.md` covers module architecture, skill interface, spending threshold, A2A protocol binding, and security model. `LEARNING.md` documents the lez-build internals research and known gaps.
+
+## Supporting Materials
+
+- `demo.sh` -- 7-step end-to-end walkthrough (wallet creation, NPK, balance, sync, program deploy, program call, A2A task).
+- `docs/DEPLOYMENT.md` -- three-agent deployment (storage-agent, messaging-agent, blockchain-agent).
+- `lez-wallet-module/lez-wallet-core/tests/integration_test.rs` -- 7 integration tests.
+- `ARCHITECTURE.md`, `LEARNING.md` -- design and research documentation.
+- `interfaces/skill.h`, `interfaces/lez_wallet.h` -- skill and wallet interface specs.
+
+## Terms & Conditions
+
+By submitting this solution, I confirm that I have read and agree to the [Terms & Conditions](../TERMS.md).