agentnet-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{agentnet_cli-0.3.0 → agentnet_cli-0.4.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 - 2026-07-23
+
+- Add every-prompt skill-fire support for Cursor and Hermes.
+- Split skill-fire hook logic into a ports-and-adapters package for cleaner connector-specific integrations.
+- Share Hermes user memory with the skill-fire relevance gate.
+- Add Cursor and Hermes hook test coverage for the new hard-nudge flow.
+- Bump bundled Hermes, hosted skill, and OpenClaw integration metadata to match the CLI release.
+
 ## 0.3.0 - 2026-07-18
 
 - Add Claude Code search-fire hook support so AgentNet can surface relevant marketplace skills during search workflows.

agentnet_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,80 @@
+# agentnet-cli
+
+CLI tool that detects AI coding agents on your system and connects them to the [Agent-net](https://agentnet.market) marketplace via MCP.
+
+## Tech Stack
+
+- **Language:** Python 3.11+ (ruff linting, 100-char line length)
+- **Package manager:** uv
+- **CLI framework:** Typer + Rich
+- **HTTP client:** httpx
+- **Testing:** pytest (475 tests), pytest-cov
+- **CI:** GitHub Actions (lint + test matrix on 3.11/3.12/3.13)
+- **Publish:** PyPI via trusted publisher (tag `v*`)
+
+## Repository Structure
+
+See [ARCHITECTURE.md](ARCHITECTURE.md). Layers:
+
+- `cli/` — Typer entry (`cli/main.py`), core commands, marketplace JSON commands
+- `connectors/` — per-agent wiring + `templates/` for file injection
+- `marketplace/` — platform client, external catalogs, skill discovery
+- `tools/` — MCP stdio server, Hermes plugin, and `skillfire/` (the every-prompt skill-fire pipeline)
+- `infra/` — config, paths, manifest
+- `src/agentnet_cli/integrations/` — Claude and OpenClaw native plugin trees (bundled in wheel)
+
+## Key Commands
+
+```bash
+uv sync --group dev              # Install deps
+uv run pytest -v                 # Run tests
+uv run pytest --cov -q           # With coverage
+uv run ruff check .              # Lint
+uv run agentnet --help           # Run locally
+```
+
+## Key Patterns
+
+- **Agent Connector:** Abstract `AgentConnector` base with `detect()`, `connect()`, `disconnect()`. Add new agents by subclassing and registering in `registry.py`.
+- **Manifest rollback:** `manifest.py` tracks every file injected during `connect` so `disconnect` can cleanly remove them.
+- **Config persistence:** `~/.agentnet/config.json` stores platform credentials (0600 permissions). Agent custom paths stored separately.
+- **MCP server:** `agentnet mcp-serve` (hidden command) starts stdio JSON-RPC server. Agents launch this as a subprocess.
+- **Marketplace commands:** All output JSON to stdout. Errors output `{"error": "..."}` with exit code 1.
+- **Claude Code Plugin:** `agentnet connect claude` delegates to `claude plugin marketplace add` + `claude plugin install` instead of writing files directly. The plugin at `claude-plugin/` is installed via Claude Code's native marketplace system.
+- **Hermes Plugin:** `agentnet connect hermes` copies the plugin to `~/.hermes/plugins/agentnet/` and skills to `~/.hermes/skills/agentnet/`, using Hermes's native plugin system.
+- **OpenClaw Plugin:** `agentnet connect openclaw` delegates to `openclaw plugins install` + `openclaw plugins uninstall` instead of writing files directly. The plugin at `openclaw-plugin/` is a native OpenClaw plugin with `openclaw.plugin.json` manifest, publishable to ClawHub.
+- **Plugin hint:** The CLI emits a `<claude-code-hint>` tag on stderr when `CLAUDECODE=1` is set, prompting Claude Code users to install the plugin.
+- **Auto-update on the hook flow:** `maybe_auto_update()` (rate-limited 24h via manifest `last_update_check_at`, gated by `AGENTNET_AUTO_UPDATE`, PyPI version check, background installer upgrade + stale-integration refresh) runs on every non-hook `agentnet` command via the Typer `@app.callback()`. The **hook** commands (`{skill,cursor,hermes}-hook`) are excluded there (`_HOOK_COMMANDS`) so `--pre`/`--peek`/`--post` never block a tool call; the update runs **once per turn from the detached `--fetch` worker** (`skillfire.run_fetch`), off the agent's critical path.
+- **Skill-fire architecture — `tools/skillfire/` (ports & adapters):** the every-prompt skill-fire pipeline shared by all three harnesses lives in `tools/skillfire/`, split by responsibility — `config.py` (constants/credentials), `session.py` (event/cache/atomic-claim primitives), `candidates.py` (skills.sh discovery), `classifier.py` (the three backend gate runners), `render.py` (**pure**, zero I/O — the fenced user-facing list), `content.py` (`npx skills use` fetch, owns that `subprocess` call site so a test patching it can't affect the classifier's or candidate-discovery's), `broker.py` (brokered-A2A fallback), `worker.py` (orchestrates discovery → classify → render → content/broker → cache, plus `spawn_worker`), `steer.py` (steer-text + the `check_steer`/`check_fallback` decisions). `tools/skillfire/__init__.py` is **the port** — the only surface the three adapters (`tools/claude_hook.py`, `tools/cursor_hook.py`, `tools/hermes_hook.py`) may import: `spawn_worker(session, prompt, *, limit, timeout, classifier)` (launch the detached worker, spawn-claim + stale-cleanup + `Popen` in one call), `check_steer(session)` (mid-run hard-nudge text or `None`), `check_fallback(session, *, timeout)` (turn-end fallback text or `None`), `run_fetch` (the CLI-invoked worker entrypoint), plus the `SUBAGENT_ENV`/`AGENTNET_SENTINEL` constants. Internals are free to reshuffle without touching an adapter or `main.py`, since none of them reach past the port. Tests mirror the module split 1:1 under `tests/skillfire/`.
+- **Every-prompt skill hook (Claude Code):** `agentnet enable-skill-fire` (and `connect claude`) install three hooks in `~/.claude/settings.json` (also bundled in the plugin's `hooks/hooks.json`), dispatched to `tools/claude_hook.py`. `UserPromptSubmit` → `agentnet skill-hook --pre` calls `skillfire.spawn_worker(..., classifier="claude")` and returns immediately (0 latency). The worker discovers **installable skill candidates** (`discover_skills` → skills.sh, each carrying a `<repo>@<slug>`) + runs a cheap no-tool `claude -p` **classifier** (Haiku) as the reliable relevance **gate** (a bare yes/no gate isn't — the model just answers). Two-phase so the outcome reaches the hooks fast: **Phase 1** caches the **recommendation list** (relevant skills by name + why + skills.sh link) the moment the gate opens (~12s); **Phase 2** *appends* the top match fetched via `npx skills use <repo>@<slug>` (which downloads the skill — SKILL.md + references — to a temp dir; single-file skills are materialized to a temp `SKILL.md`) as a **concise header (name + description) + the on-disk path**, not a full SKILL.md dump. The injected outcome is thus the list *then* "Reading the top match and applying it." + that block — the agent surfaces the list and reads/applies the methodology from disk, which is what makes it *act* on the skill rather than just mention it. No files are written to the repo. If content is unavailable (no `npx`/all fetches miss), Phase 2 falls back — behind the same open gate — to the live **Skills Agent** over **brokered A2A**: `PlatformClient.use_agent(agent_id="agentnet-skills-agent", task=…)` with the user's `setup` identity; the platform relays A2A and returns `{status:"settled", agent_response}` in one call. **No skills-agent token is ever held client-side.** Only a `settled` response is used. Injection is layered: `PostToolUse` → `agentnet skill-hook --peek` calls `skillfire.check_steer` to force-steer the agent **mid-flight** once the outcome is ready (`{"decision":"block","reason":…}`); `Stop` → `agentnet skill-hook --post` calls `skillfire.check_fallback`, the guaranteed fallback (`{"decision":"block", …additionalContext}`) for no-tool answers. Because the hooks are registered in **both** `settings.json` (via `connect`/`enable-skill-fire`) and the plugin's `hooks.json`, Claude Code may run each twice in parallel — so idempotence is enforced with **atomic `O_EXCL` once-claims** inside `session.py`: a per-`(session,prompt)` **spawn marker** so duplicate `--pre` hooks spawn exactly one worker (not 2× classifier cost), and a per-prompt **emit marker** shared by peek + post so exactly one steer fires (and a re-fired `Stop` no-ops). The cache carries a **`final`** flag: Phase 1 writes `final:false` (the list names skills but has no methodology), Phase 2 writes `final:true` once content is attached — or promotes the list to `final` when no content is reachable. **A mid-run steer only fires on a `final` outcome**, so it can't burn its one shot on a list the agent has nothing to apply from; the `Stop`/fallback surface takes a non-final list as a last resort. Session-keyed JSON cache `$TMPDIR/agentnet-skill/<session>.json` (`{outcome, final}`) + sibling `.emitted`/`.<hash>.spawn` markers; `AGENTNET_SKILL_SUBAGENT=1` guards recursion. All best-effort — no token/binary/candidates/unreachable-platform/timeout injects nothing. `agent_id` overridable via `AGENTNET_SKILLS_AGENT_ID`/config. Implemented in `tools/skillfire/` + `tools/claude_hook.py` + `connectors/claude_search_hook.py`.
+
+- **Every-prompt skill hook (Cursor):** `agentnet connect cursor` also installs three hooks in `~/.cursor/hooks.json` (`connectors/cursor_hook.py`) that call the *same* `skillfire` port as Claude — only the thin I/O adapter differs (`tools/cursor_hook.py`, command `agentnet cursor-hook --pre/--peek/--post`; session key is Cursor's `conversation_id`). `beforeSubmitPrompt` → `--pre` calls `spawn_worker(..., classifier="cursor")` and allows the prompt (`{"continue":true}` — this event can't inject). `preToolUse` → `--peek` is the **hard nudge**: Cursor's only forceful steer is a denied action, so `check_steer` denies the first tool call **once** (`{"permission":"deny","agent_message":…}`) once the outcome is ready, and the agent must read+apply the skill then retry; every later call is allowed. `stop` → `--post` calls `check_fallback`, the fallback for no-tool answers via `followup_message` (auto-submitted next turn); it's `[AgentNet]`-tagged so the re-fired `--pre` recognizes its own injection and won't loop. The relevance **gate runs on the user's own Cursor model** via `cursor-agent -p --mode ask --output-format text --trust` (`classify(backend="cursor")` in `tools/skillfire/classifier.py`). The backend-aware classifier tries the requested CLI first and falls back to the other (`claude -p` ↔ `cursor-agent -p`) so a machine with only one still gates; Cursor needs `cursor-agent login` (auth), and `AGENTNET_CURSOR_CLASSIFIER_MODEL` pins a cheaper/faster gate model than the default.
+
+- **Every-prompt skill hook (Hermes):** `agentnet connect hermes` also installs three **shell hooks** in `~/.hermes/config.yaml` (`connectors/hermes_hook.py`), calling the *same* `skillfire` port; only the I/O adapter differs (`tools/hermes_hook.py`, `agentnet hermes-hook --pre/--peek/--post`; session key is `session_id`, the prompt is `extra.user_message`). `pre_llm_call` → `--pre` calls `spawn_worker(..., classifier="hermes")` (Hermes' documented `UserPromptSubmit` equivalent; it *can* inject `{"context":…}` but the worker needs ~20s, so the steer lands later). `pre_tool_call` → `--peek` is the hard nudge: Hermes **natively accepts the Claude-Code `{"decision":"block","reason":…}` shape** (it normalizes to `{"action":"block","message":…}`) and returns the reason to the model as the tool's error, so it re-plans inline. `pre_verify` → `--post` fires when the agent edited code and is about to finish; `{"action":"continue","message":…}` appends a synthetic user turn (gated on `extra.attempt` since it re-fires per nudge, bounded by `agent.max_verify_nudges`). Gate backend `hermes` runs an **in-process `AIAgent`** on the user's own model via `gateway.run._resolve_gateway_model` + `_resolve_runtime_agent_kwargs` (no subprocess, no separate auth; `skip_memory=False` shares the user's memory/profile so the gate ranks per-user, while `disabled_toolsets` (incl. `memory`) + `max_iterations=1` keep it a one-shot classify), falling back to the CLI backends when not importable. Shell hooks need **consent** — install writes scoped entries to `~/.hermes/shell-hooks-allowlist.json` for our three commands only (narrower than global `hooks_auto_accept`), and registers the **absolute** binary path since `hermes hooks doctor` stats the command's first token. Verify headlessly with `hermes hooks list` / `doctor` / `test <event> --payload-file`.
+
+## Testing Patterns
+
+- **CLI tests:** `typer.testing.CliRunner` + `fake_home` fixture (temp dir with patched `Path.home()`)
+- **HTTP tests:** `httpx.MockTransport` for platform API mocking
+- **MCP tests:** Mock stdin/stdout with `io.StringIO`, mock `ToolHandlers`
+- **Agent tests:** Create fake config dirs in `fake_home` to simulate installed agents
+
+## CI/CD
+
+- **CI (`ci.yml`):** Lint (ruff) + tests across Python 3.11/3.12/3.13 on PRs and pushes to main
+- **Publish (`publish.yml`):** Tags matching `v*` trigger PyPI publish via trusted publisher (OIDC)
+
+## Documentation Requirements
+
+After any change that affects the project's public interface, structure, or developer workflow, update the relevant docs before committing:
+
+- **README.md** — Update if commands, flags, supported agents, install steps, or architecture change
+- **CLAUDE.md** — Update if repo structure, key patterns, test counts, or commands change
+- **Inline docstrings** — Update if a function's contract (params, return, side effects) changes
+
+Do not leave docs describing old behavior. If you add a command, it goes in the README. If you add a test file, update the test count here. If you change a pattern, update the Key Patterns section.
+
+## Related Repos
+
+- [agentnet-platform](https://github.com/TheAgent-net/agentnet-platform) — FastAPI backend
+- [agentnet-frontend](https://github.com/TheAgent-net/agentnet-frontend) — Admin dashboard, user dashboard, marketplace SPAs