AgentHub/docs/superpowers/specs/2026-09-28-ai-tools-a2-design.md

AI Tools — part A2: install, update, remote catalog, favicons

Issue: #40. Date: 2026-09-28. Status: design agreed in chat, self-reviewed, awaiting spec review. Builds on A1 (2026-09-28-ai-tools-a1-design.md, whose § "A2 decisions" this refines).

Goals

• An Install button on "Available to install" rows for the tools whose install command is known; a confirm dialog shows exactly what will run; a live log appears under the row; the tool is re-detected (and enabled) when the job ends.
• Update on installed rows, a "new version" badge for npm-distributed tools, and Update tools in the section header (named so, not "Update all", because Settings already has an Update all for plugins).
• The catalog refreshes itself daily from the newest AgentHub release, so a new tool or a fixed flag reaches an install without a plugin update.
• Real icons, fetched by the server, never by the browser.

Non-goals

• Install data for every tool. A2 ships it for a verified few (§ 1); the remote catalog can add more later.
• sudo, Homebrew, uv, pipx. A system-wide Node's EACCES is reported, not worked around.
• Uninstall. A job surviving a server restart (it is a child of the server and dies with it; the log is lost, the tool is re-detected on next start).

1. Catalog fields

Two optional fields in a catalog file:

• install: { "kind": "npm", "package": "<name>" } or { "kind": "script", "url": "https://…" }.
  • package matches ^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$.
  • url is https: and its host shares its last two labels with the host of the file's homepageUrl. (ponytail: two-label compare, not a public suffix list — wrong for co.uk-style hosts, none in the catalog; swap in a PSL if one arrives.) Against a malicious remote catalog this is only a sanity check — that file controls homepageUrl too; the trust is the forge's (§ 3).
• update: { "kind": "npm" } (needs install.kind === "npm", reuses its package), { "kind": "script" } (re-runs install.url), or { "kind": "self", "args": ["update"] } (the tool's own updater, run as [<detected path>, ...args]).

A file with a bad install/update is rejected whole, like any A1 rule. A file from DASHBOARD_AI_TOOLS_DIR may not carry either field (nor launcher, as in A1) — that directory is writable by anyone who can drop a file, and an Install click would run what it names.

First batch (npm owners checked with npm view <pkg> maintainers on 2026-09-28; each package's bin matches the catalog's detect):

id	install	update
codex	npm @openai/codex	npm
gemini	npm @google/gemini-cli	npm
qwen-code	npm @qwen-code/qwen-code	npm
opencode	npm opencode-ai	npm
copilot	npm @github/copilot	npm
amp	npm @sourcegraph/amp	npm
cursor	script https://cursor.com/install	script
claude	— (always present: it runs AgentHub)	self ["update"]

Antigravity gets neither until its updater is known.

2. Jobs — server/lib/ai-tool-jobs.js

• ONE job at a time, server-wide. A second request answers 409 EBUSY.
• A job is { id, tool, action: "install"|"update", status: "running"|"ok"|"failed", startedAt, endedAt, exitCode, log }, kept in memory; log is stdout+stderr, capped at 256 KB (the head is dropped). After it ends it stays readable until the next job starts.
• The argv comes only from the catalog entry:
  • npm install/update: [<npm>, "install", "-g", "<package>@latest"], where <npm> is resolved on the login shell's own PATH, in the shell's order — not on process.env.PATH, where hydrateShellPath APPENDS the shell's directories after the unit's, so the pinned nvm Node's npm would still win, and -g there lands where the user's PATH never looks (the tool would "install" and stay undetected). shell-path.js therefore keeps the last shell PATH it read (shellPath(), null when hydration is off or failed ⇒ fall back to process.env.PATH), and a job's env PATH is shellPath() followed by process.env.PATH, so npm's own #!/usr/bin/env node picks the matching Node.
  • script: the server downloads url (https, 15 s timeout, ≤ 1 MB, the final URL after redirects must still be https on the same two-label host) to a 0600 temp file and runs ["bash", <file>]; the file is deleted after.
  • self: [<detected path>, ...args].
• execFile/spawn with an argv, never a shell; stdin is ignore; env is the server's env with the hydrated PATH; each command runs in its own process group (detached), and a 10-minute timeout sends the whole group SIGTERM, then SIGKILL after 5 s (failed, ETIMEDOUT in the log). A step ends on close, or 500 ms after exit — a daemon an installer left behind can hold the pipes forever, and close alone would keep the job (and EBUSY) alive.
• On an EACCES in an npm job's output, the log gets one hint line: Node is installed system-wide, use a user-level Node (nvm/fnm) or install by hand.
• When a job ends: shell-path hydrate + aiTools.refresh(); a successful install also sets the tool enabled: true; the version cache is dropped (§ 3) — and only THEN does the status leave running, because the client refetches once, on the first poll that sees it finished. A failure in that bookkeeping is appended to the log, never thrown.

3. Versions and the remote catalog

npm-managed. An installed tool counts as npm-managed only when the realpath of its detected binary lies under <npm prefix -g> (read once per versions pass with the § 2 npm). A tool installed another way — this machine's codex is Codex's standalone build under ~/.codex/packages/standalone/ — gets NO npm Update and no badge: an npm update would install a second copy the PATH order shadows, and the badge would never clear. Its row says Installed outside npm instead.

Versions (update.kind === "npm", npm-managed tools only): installed = first \d+\.\d+\.\d+ in <path> --version; latest = npm view <pkg> version. All tools in parallel, 5 s timeout each, cached in memory for 24 h, computed lazily on the first GET /api/ai-tools/versions and on Refresh. updateAvailable = latest > installed by the same compare update-check.js uses. Offline or unparsable ⇒ no badge, no error.

Remote catalog (server/lib/ai-tools-sync.js):

• Daily (and once 60 s after start), off with AGENTHUB_AI_TOOLS_SYNC=0.
• Resolves the repo URL exactly as update-check.js does — marketplace manifest for a plugin-cache install, the canonical git remote for a checkout — through a new export repoUrlFor(root) there (built from its existing detectPluginInstall/pluginMarketplaceUrl/pickCanonicalRemote), and reads the newest release through fetchReleaseFromUrl.
• Only when that release is NEWER than the running build's package.json version — a dev checkout ahead of the newest release must never be rolled back to older data.
• Lists server/data/ai-tools/ at the release tag through the forge contents API (/api/v1/repos/<o>/<r>/contents/server/data/ai-tools?ref=<tag>, the Gitea/Forgejo shape releaseApiUrl already builds), downloads each *.json (≤ 64 KB each, ≤ 200 files), validates each with A1's validate at release trust (may carry launcher, install, update), and writes the set atomically to <runtime dir>/ai-tools-remote/ with a meta.json (tag, fetchedAt). A failed sync leaves the previous set untouched.
• Precedence per id: DASHBOARD_AI_TOOLS_DIR › remote › built-in. A remote set whose tag is no longer newer than the running build (the user upgraded) is ignored.
• GET /api/ai-tools gains catalog: { source: "builtin"|"remote", tag, fetchedAt }.

4. Icons — GET /api/ai-tools/:id/icon

• Domain = the file's faviconDomain, else the homepageUrl host. It must be a dotted hostname (^[a-z0-9.-]+\.[a-z]{2,}$, no IP literal, no port).
• The server fetches https://<domain>/favicon.ico (10 s, ≤ 256 KB — multi-resolution .ico files run past 100 KB — final URL https on the same site — last two host labels, so github.com → github.githubassets.com is refused but www. redirects pass), accepts only PNG, ICO, JPEG, GIF, WebP recognised by their magic bytes (the Content-Type header is ignored: sites omit or mislabel it) — never SVG, which would run script on the dashboard's origin if the URL were opened directly — and caches it in <runtime dir>/ai-tool-icons/. A failure is cached for 24 h as a miss.
• Served with the cached type, X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox, Cache-Control: max-age=86400; a miss is 204 (a 404 would log a console error per letter avatar on every visit) and the client keeps its letter avatar; an unknown id is 404.

5. API

All writes behind sameOriginGuard; nothing in a body names a command.

Route	Does
POST /api/ai-tools/:id/install	starts the install job → 202 {job}; 404 ENOTOOL, 400 ENOINSTALL (no install), 409 EINSTALLED, 409 EBUSY
POST /api/ai-tools/:id/update	starts the update job; 400 ENOUPDATE, 409 ENOTINSTALLED, 409 ENOTNPM (npm update on a tool installed outside npm), 409 EBUSY
POST /api/ai-tools/update-all	one job that updates, in catalog order, every npm-managed tool with updateAvailable plus every installed tool with a self updater; its log concatenates each step's; 400 ENOTHING when the list is empty
GET /api/ai-tools/job	the current or last job, or null
GET /api/ai-tools/versions	{ [id]: { npmManaged, installed, latest, updateAvailable } } for tools with update.kind === "npm"
GET /api/ai-tools/:id/icon	§ 4

GET /api/ai-tools rows gain install ({kind, package?|url?} or null) and update ({kind}, plus args for self, or null) so the dialog can show the exact command.

6. UI (AiToolsSettings.tsx, useAiTools.ts)

• Avatar: <img src="/api/ai-tools/:id/icon">, letter avatar on onError.
• Available row with install: Install → confirm dialog showing npm install -g <package>@latest or Download and run <url> with bash, plus the homepage link. On confirm: POST, then poll GET /job every 1 s while running; the log renders under that row in a <pre> (monospace, max-height, auto-scroll); on end the list refetches.
• Installed row with update: Update (same dialog and log) — for an npm update only when npmManaged, else the Installed outside npm note — and a badge v<latest> available when updateAvailable.
• Header: Update tools beside Refresh, enabled when a badge or a self updater exists; its dialog lists what will run.
• Every job button is disabled while a job runs; a page opened mid-job picks it up from GET /job.

7. Testing

Server (npm run test:server): field validation (bad package names, a script off the homepage's host, install in DASHBOARD_AI_TOOLS_DIR rejected, update: npm without npm install); jobs with an injected exec (argv exactly as § 2, npm resolved from the shell's own PATH ahead of the unit's, one-at-a-time EBUSY, log cap, timeout, enable-after-install, EACCES hint); script download guards (size, https, redirect host); version parse/compare, the 24 h cache, npm-managed by realpath under the global prefix; sync (newer-only, precedence, atomic replace, a failed sync keeps the old set, release-trust launcher); icon guards (type allowlist without SVG, size, IP-literal domain refused, headers). Client (npm run test:client): Install confirm shows the exact command, the log polls and stops, badge and Update tools, avatar fallback.

8. Docs

CLAUDE.md marker, AGENTS.md, docs/API.md (six routes), server/README.md, server/data/ai-tools/README.md (the two fields, the trust rules), server/openapi-extra/ + regenerated openapi.yaml, the env var AGENTHUB_AI_TOOLS_SYNC wherever env vars are listed, and the update-project-docs pass.