m2-market/docs/scout.md

Solution Scout v0

Solution Scout is a Hermes plugin that watches safe turn summaries, searches the M2 Marketplace catalog, and shows a non-blocking proposal when a published Solution appears to cover the current task.

Install

./scout/install.sh

The installer is an idempotent file drop to:

• ~/.hermes/plugins/m2-solution-scout/plugin.yaml
• ~/.hermes/plugins/m2-solution-scout/__init__.py
• ~/.config/m2-market/pull-policy.toml only when that file does not already exist

It does not enable Scout. To opt in, edit ~/.config/m2-market/pull-policy.toml and set:

[scout]
enabled = true
tenant_id = "machine-machine"
desktop_id = "chris-m2o"
operator_id = "op_chris"

Guardrails

Scout fails closed. Missing config, enabled=false, or a missing tenant_id makes every hook a no-op. raw_keystrokes=true or raw_client_data=true refuses session start. The plugin summarizes and redacts on-box before memory-api egress, searches only agent_id = "market:catalog", filters hits by tenant_visibility containing the desktop tenant or "*", rate-limits proposals, and never calls m2-market install.

Event Flow

On on_session_start, the plugin loads pull-policy.toml. On post_llm_call, it gates on policy, rate caps, and cooldowns, then starts a background thread so slow catalog queries do not block the operator turn. The worker builds an m2.scout.intent_summary.v1, posts /memory/search with agent_id=market:catalog, applies client-side tenant filtering and threshold checks, builds an m2.scout.proposal.v1, shows notify-send with a Store deep link, and falls back to the Herdr socket toast when desktop notification delivery is unavailable.

The deep link format is:

m2store://listing/{listing_id}?proposal_id={proposal_id}&source=scout

Telemetry Paths

Local state lives at:

~/.local/share/m2-market/scout/state.json

Proposal telemetry is append-only JSONL:

~/.local/share/m2-market/scout/outbox/YYYY-MM-DD.jsonl

The v0 plugin records proposal_shown locally for later batching to market:evidence. Accept, dismiss, debit, grant, and install remain owned by M2 Store and m2-market.