Use carried agents and npm CLI installer by tkkhq · Pull Request #4 · Kong/volcano-agentic-plugins

tkkhq · 2026-07-09T16:41:56Z

Summary

sync updated volcano-skills content and submodule pointer from Use plugin-carried agents and npm CLI install volcano-skills#1
remove inert materialized skills/CLAUDE.md copies
make plugin-carried skills/AGENTS.md primary, while installer also maintains ~/.volcano/AGENTS.md as fallback/reference
update install-volcano surfaces to install @volcano.dev/cli from npm by default, with GitHub release download fallback
update ~/.claude/CLAUDE.md managed block handling to replace existing Volcano blocks and include @~/.volcano/AGENTS.md
update installer validation assertions and VS Code/Claude Desktop surfaces

Validation

node scripts/check-skill-drift.mjs
node scripts/check-no-content-duplicates.mjs
node scripts/check-install-entrypoints.mjs
node scripts/check-codex.mjs
node scripts/check-claude-desktop.mjs

tkkhq · 2026-07-09T16:46:32Z

Updated after review: install-volcano is now adaptive. If it finds a plugin-carried skills directory, it keeps skills in the plugin and copies AGENTS.md to ~/.volcano/AGENTS.md as fallback. If no plugin skills directory is found (manual/non-plugin path), it installs AGENTS.md and downloads skills from VOLCANO_WEB_URL into ~/.volcano/skills for runtime discovery. Re-ran validation: skill drift, duplicates, install entrypoints, Codex, Claude Desktop.

Copilot

Pull request overview

This PR shifts the Volcano plugins toward treating the plugin-carried skills/AGENTS.md as the primary instruction source and changes the CLI installer to prefer an npm install of @volcano.dev/cli@latest, falling back to the GitHub release download. It also removes the now-inert materialized skills/CLAUDE.md copies and syncs updated volcano-skills content/submodule pointer. The installer additionally maintains ~/.volcano/AGENTS.md as a durable fallback and manages a Volcano block in an existing ~/.claude/CLAUDE.md.

Changes:

Installer now runs npm install -g @volcano.dev/cli@latest by default, with the GitHub release download demoted to a fallback (new install_cli_from_npm/npm_global_bin_dir helpers).
New install_agents_fallback, find_plugin_skills_dir, valid_agents_md, upsert_block, and wire_existing_claude_config helpers copy the carried AGENTS.md to ~/.volcano/AGENTS.md and wire an existing global CLAUDE.md.
Removed skills/CLAUDE.md across plugins; reworked AGENTS.md prerequisites/bootstrap guidance and updated check-install-entrypoints.mjs assertions plus VS Code/Claude Desktop surfaces.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/check-install-entrypoints.mjs	Updates installer assertions to require npm install and keep release download as fallback
plugins/vscode/src/extension.ts	Embeds the updated install script (npm-first + AGENTS.md fallback + Claude wiring)
plugins/vscode/README.md	Documents the new npm-first install behavior
plugins/{cursor,claude-code,claude-desktop,codex}/skills/install-volcano/SKILL.md	Adds npm install + AGENTS.md fallback + Claude wiring to installer skills
plugins/{cursor,claude-code}/commands/install-volcano.md	Mirrors the installer skill content in the command surfaces
plugins/{cursor,claude-code,claude-desktop,codex}/skills/AGENTS.md	Rewrites prerequisites and adds a guarded, env-driven bootstrap fallback
plugins/{cursor,claude-code,claude-desktop,codex}/skills/CLAUDE.md	Removes the inert Claude-Code wrapper copies
plugins/claude-desktop/server/index.js	Embeds the updated install script and refreshes setup instructions text

Comments suppressed due to low confidence (1)

plugins/cursor/skills/install-volcano/SKILL.md:330

These two calls run under set -eu and are placed after the block that already logs "Volcano CLI ready" (and exit 1s only when the CLI is absent). Unlike the other optional steps in this script (e.g. install_cli_from_npm || install_cli_from_release, volcano --version || true, bin_dir=... || true), these two are unguarded. install_agents_fallback returns non-zero when no plugin skills directory is found and the AGENTS.md download fails/returns HTML, so set -e will abort the whole script with a non-zero status even though the CLI itself installed successfully, and wire_existing_claude_config is then skipped. Since the plugin-carried skills are described as the primary source and ~/.volcano/AGENTS.md only as a fallback, a fallback failure probably should not fail the entire install. Consider guarding these (e.g. install_agents_fallback || true) or handling their failure explicitly. This is duplicated across all plugin install-volcano scripts and the two JS-embedded copies.

  ext=""
  [ "$os" = "windows" ] && ext=".exe"

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+valid_agents_md() {
+  file="$1"
+  [ -s "$file" ] || return 1
+  if head -c 200 "$file" | grep -qi '<!doctype html\|<html'; then


+   curl -fsSL "$VOLCANO_WEB_URL/bootstrap.sh" -o /tmp/volcano-bootstrap.sh
+   # Guard against SPA/CDN fallbacks that return HTTP 200 with an HTML shell
+   # instead of a real 404 for missing paths (curl -f only catches HTTP errors).
+   if head -c 200 /tmp/volcano-bootstrap.sh | grep -qi '<!doctype html\|<html'; then


tkkhq · 2026-07-09T20:02:05Z

Verified against the live npm package: resolves to 0.0.5, exposes , requires Node >=18, and a temp-prefix install produced . Installer assumptions still hold; no further plugin changes needed.

tkkhq · 2026-07-09T20:02:17Z

Correction/verification: verified against the live npm package. @volcano.dev/cli@latest resolves to 0.0.5, exposes bin.volcano = bin/volcano.js, requires Node >=18, and a temp-prefix install produced volcano v0.0.5. Installer assumptions still hold; no further plugin changes needed.

tkkhq · 2026-07-10T16:21:45Z

Follow-up alignment: install-volcano now persists/removes api_url exclusively in ~/.volcano/config.json (no secondary API env file), while an explicitly supplied VOLCANO_API_URL remains the runtime override. The canonical skill, materialized plugin skills, Claude/Cursor commands, VS Code installer, and Claude Desktop installer were regenerated together. Verified by plugin installer smoke test and all repository checks. This depends on CLI support in Kong/volcano-cli#44.

tkkhq · 2026-07-10T20:43:49Z

Scope cleanup in e5d112e: removed all API URL persistence/config mutation from plugin installer surfaces. VOLCANO_API_URL remains process-only for maintainers/developers; end users use the CLI compiled production endpoint. Canonical skill and all generated command/embedded installer copies are synced and checks pass.

tkkhq · 2026-07-10T22:59:03Z

Addressed all outstanding Copilot findings from the initial review, verified against current HEAD:

Portable HTML guard: AGENTS.md's bootstrap fallback still used GNU-only grep -qi ... \| (BSD/macOS grep treats \| literally). Fixed to grep -qiE '<!doctype html|<html' in 68b51ad; verified detection works under BSD grep semantics.
Command/skill mislabeling: plugins/cursor/commands/install-volcano.md and plugins/claude-code/commands/install-volcano.md said "this skill" but are Cursor/Claude Code slash-commands. Fixed to "this command" in 68b51ad.
Low-confidence finding (unguarded fallback abort): install_volcano_content (renamed since the original review, previously install_agents_fallback) can still return 1 and was called bare under set -eu, which would skip wire_existing_claude_config on a fallback/network failure. Guarded in 8ea0904: install_volcano_content || warn .... Verified via smoke test — a failed AGENTS.md fetch now still wires the managed ~/.claude/CLAUDE.md block (exit 0).

All checks re-run and passing: skill drift, no-content-duplicates, install-entrypoints, Codex, Claude Desktop.

Copilot AI review requested due to automatic review settings July 9, 2026 16:41

Copilot started reviewing on behalf of tkkhq July 9, 2026 16:42 View session

Use carried agents and npm CLI installer

df98bf2

tkkhq force-pushed the fix/plugin-carried-agents-npm-cli branch from 1bd6432 to df98bf2 Compare July 9, 2026 16:46

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Persist plugin API URL in cli config

033e050

tkkhq added 2 commits July 10, 2026 16:07

Sync hardened CLI installer surfaces

b2e348f

Remove API persistence from plugin installers

e5d112e

tkkhq added 2 commits July 10, 2026 18:58

Fix copilot findings for grep portability and command wording

68b51ad

Sync guarded fallback install for claude wiring

8ea0904

Update skills submodule pointer to merged main

347ad39

tkkhq added this pull request to the merge queue Jul 10, 2026

Merged via the queue into main with commit fbc5fef Jul 10, 2026
4 checks passed

tkkhq deleted the fix/plugin-carried-agents-npm-cli branch July 10, 2026 23:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Use carried agents and npm CLI installer#4

Use carried agents and npm CLI installer#4
tkkhq merged 7 commits into
mainfrom
fix/plugin-carried-agents-npm-cli

tkkhq commented Jul 9, 2026

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

tkkhq commented Jul 9, 2026

Summary

Validation

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

tkkhq commented Jul 9, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

tkkhq commented Jul 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants