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

agentnet_cli-0.4.1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.4.1 - 2026-07-23
+
+- Add Claude-safe skill-fire steer wording and system-message support.
+- Include platform usage context in skill-fire discovery flows.
+- Refresh README placement for the agent bootstrap command.
+- Bump bundled Hermes, hosted skill, and OpenClaw integration metadata to match the CLI release.
+
+## 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.
+- Add `agentnet enable-search-fire` for one-command Claude hook installation.
+- Preserve malformed Claude settings files instead of overwriting them during connector setup.
+- Add setup telemetry hooks and a platform client telemetry helper.
+- Bump bundled Hermes, hosted skill, and OpenClaw integration metadata to match the CLI release.

agentnet_cli-0.4.1/CLAUDE.md

@@ -0,0 +1,82 @@
+# 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 (511 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)`/`check_fallback(session, *, timeout)` (the shared, wrapped decision — mid-run/fallback text or `None` — used by Cursor/Hermes), `check_steer_raw`/`check_fallback_raw` (same decision, bare outcome with no wrapper text, so a harness can build its own presentation — used by Claude, see below), `run_fetch` (the CLI-invoked worker entrypoint), plus the `SUBAGENT_ENV`/`AGENTNET_SENTINEL` constants. The `_raw` variants are purely additive — appended to `steer.py`, never touching `check_steer`/`check_fallback`'s own bodies — so Cursor/Hermes are byte-for-byte unaffected by anything Claude-specific. 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_raw` (the bare outcome, no wrapper) to force-steer the agent **mid-flight** once the outcome is ready (`{"decision":"block","reason":…, "systemMessage":…}`); `Stop` → `agentnet skill-hook --post` calls `skillfire.check_fallback_raw`, the guaranteed fallback (`{"decision":"block", "systemMessage":…, …additionalContext}`) for no-tool answers. Claude builds its **own** plain-language wording in `claude_hook.py` rather than the shared `steer_reason`/`fold_context` Cursor/Hermes use (see below) — no STEP-numbered "reproduce this verbatim" scaffolding, and no claim that any section is hidden from the user. Reason: Claude Code prints the entire `reason`/`additionalContext` payload to the user's terminal (native CLI behavior), so the shared wording's `AGENT_ONLY` label ("do not show the user") is an observable lie there — live testing showed a session flag it as a probable prompt injection and refuse to comply. `systemMessage` (set on both events) is a separate, platform-guaranteed display channel — never passed to the model, shown to the user regardless of what the model does next — so the skill list's visibility no longer depends on model compliance the way `reason`/`additionalContext` do. 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`.
+
+- **Platform call context & usage analytics:** the skill-fire pipeline attaches optional call context to its platform calls, but **the gate model rides only on post-classification records, never on the retrieval call.** `GET /skills/discover` (`marketplace/skills/discovery.py`) is candidate *retrieval* — it fires **before** the classifier runs, so which model/backend will gate is unknown there (and the backend can fall back), so it carries **only** `harness` (`claude`/`cursor`/`hermes`, the requested backend — still which IDE the user is in, unaffected by fallback) and `session_id`. The **post-gate** records — the brokered `POST /agents/{id}/use` (`marketplace/client.py::use_agent`, via `broker.negotiate_via_platform`) and the usage-telemetry `POST /skills/discover/feedback` (`broker.report_recommendation`) — additionally carry `classifier_model` and `model`, resolved for the **backend that *actually* ran** (`classify()` returns `(relevant, actual_backend)`; `worker.py` resolves the model from `actual_backend`, not the requested one). `classifier_model` comes from `classifier.resolve_classifier_model()`, a pure per-backend lookup done *without* invoking the classifier: the fixed `SUBAGENT_MODEL` constant for Claude, the `AGENTNET_CURSOR_CLASSIFIER_MODEL` env value for Cursor if pinned, `_resolve_gateway_model()` for Hermes. `model` is Hermes-only — identical to `classifier_model`, since Hermes classifies on the user's own model in-process; confirmed unobtainable for Claude/Cursor (no hooked event payload exposes the driving model, per Claude Code's own hook docs). Because discovery makes **no** model claim, its record can never *conflict* with the authoritative model on the feedback/broker record for the same recommendation. Every field is added only when resolvable — omitted, never sent as `null` or guessed — and the platform's routes ignore unrecognized query params/JSON keys by default, so this ships independently of the platform's own timeline. `broker.report_recommendation()` fires the feedback `POST` the moment the classifier gate opens (non-empty relevant list) — usage telemetry for "which skills get recommended," dispatched to a **daemon thread** so it never delays the phase-1 cache write, and **`.join()`-ed (bounded by `config.REPORT_JOIN_TIMEOUT`) right before the worker returns** so a fast-exiting process doesn't kill the thread before its HTTP call lands. Wrapped in the same try/except-everywhere pattern as every other platform call here, so a `404` (route not yet live) is silently absorbed exactly like a network failure would be. The feedback payload matches the platform's `SkillFeedbackRequest` exactly (`use_case`, `recommended:[{name,why,score}]` with `score` always a `str|None`, `harness`, `session_id`, `classifier_model`, `model`). Verified end-to-end (not just unit-tested) against a real local platform build: a genuine `uvicorn` server, real FastAPI/Pydantic validation, unmodified CLI code, only the DB session/auth resolution mocked.
+
+## 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