# AI Tools A1 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** AgentHub knows ~38 AI coding CLIs from a JSON catalog, detects which are installed, lets the user enable/disable them and pick a default, and runs a lane on any of them.

**Architecture:** One server module `server/lib/ai-tools.js` owns catalog load/validation, PATH detection and the enable/default state file; `server/lib/shell-path.js` hydrates `process.env.PATH` from the login shell. `pty-run.js` keeps its Claude/Codex builders (`launcher`) and gains one generic catalog builder. The client reads everything through one hook, `useAiTools`.

**Tech Stack:** Node/Express + better-sqlite3 (server, `node:test`), React + Vite + vitest (client), tmux.

**Spec:** `docs/superpowers/specs/2026-09-28-ai-tools-a1-design.md`

## Global Constraints

- Catalog id: `^[a-z0-9][a-z0-9-]{0,39}$`; `detect`/`requires` entries are bare names, no `/`.
- `launcher` is accepted only in built-in files (`"claude"|"codex"`).
- Args and env only ever come from the catalog; the prompt is ONE argv element or a tmux paste buffer; never a shell string.
- Bypass args are emitted only when the run request carries `bypass: true`; never remembered.
- State file: `<getDataDir()>/ai-tools.json` = `{ "disabled": [], "default": null }`.
- PATH hydration: `$SHELL` (fallback `/bin/bash`) `-ilc`, delimiters, 5 s timeout, stdin ignored, after listen, off with `AGENTHUB_SHELL_PATH=0`.
- `routerCapable` = `claude`, `codex` only.
- Every new source file starts with the header ending `@author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>`.
- Server tests: `npm run test:server`; client: `cd client && NODE_ENV=test npx vitest run`; commits: `NODE_ENV=test git commit` (hook runs both suites, long timeout).
- Never push without an explicit ask.

---

### Task 1: Catalog, detection, state (`server/lib/ai-tools.js`)

**Files:**
- Create: `server/lib/ai-tools.js`, `server/data/ai-tools/*.json` (38 files), `server/data/ai-tools/README.md`
- Test: `server/__tests__/ai-tools.test.js`

**Interfaces (Produces):**
- `list(): Tool[]` — catalog order: `claude`, `codex`, then by label.
- `get(id): Tool|null`, `has(id): boolean`
- `detect(id): {installed, path, command}` (cached), `refresh()` clears the cache and re-reads the catalog.
- `readState(): {disabled: string[], default: string|null}`, `isEnabled(id)`, `setEnabled(id, bool)`, `setDefault(id)` (throws `ENOTOOL` / `EBADDEFAULT`), `effectiveDefault(): string|null`
- `view(): {tools: ToolView[], default}` — the GET body.
- `ROUTER_CAPABLE = new Set(["claude","codex"])`
- `__setCatalogDirs([...])` test seam (built-in dir, custom dir).
- `Tool = {id,label,detect,requires,args,homepageUrl,faviconDomain,prompt,resume,bypass,bypassEnv,launcher,source}`.

- [ ] Write failing tests: bad id skipped; `/` in detect skipped; non-array args skipped; `launcher` in custom file skipped; custom id replaces built-in; detection over a temp PATH with an executable and a non-executable file; `requires` missing ⇒ not installed; enable/default rules (default falls back to claude, then first installed enabled; disabling the default clears it; `EBADDEFAULT` for not-installed/disabled; `ENOTOOL` unknown).
- [ ] Implement; write the 38 JSON files from the Orca table (spec §1 mapping); README attribution (Orca MIT).
- [ ] `npm run test:server` green.

### Task 2: PATH hydration (`server/lib/shell-path.js`)

**Interfaces:** `hydrateShellPath({spawn?, shell?, timeoutMs?}) : Promise<boolean>` — merges new segments into `process.env.PATH`, returns whether it ran.

- [ ] Tests with an injected `spawn` (execFile-like): delimiters with noisy rc output, timeout, spawn error, `AGENTHUB_SHELL_PATH=0`, no duplicate segments.
- [ ] Implement with `child_process.execFile(shell, ["-ilc", "printf '__AGENTHUB_PATH__%s__AGENTHUB_PATH__' \"$PATH\""], {timeout:5000, stdio ignore stdin})`.

### Task 3: Routes `/api/ai-tools`

**Files:** Create `server/routes/ai-tools.js`, `server/openapi-extra/ai-tools.js`; modify `server/index.js` (mount + hydrate after listen), `server/openapi-extra.js`, `server/routes/run.js` (binary probe via catalog).
- `GET /` → `view()`; `POST /refresh` → hydrate, `refresh()`, `view()`; `PUT /:id {enabled?, default?:true}`. Mutations behind `sameOriginGuard`.
- [ ] Route test (pattern: `git-credentials-route.test.js`): GET shape, PUT enable/disable, default errors, `/api/run/binary?tool=nope` 400, `?tool=antigravity` resolves through catalog.

### Task 4: Lanes and spawn on any tool

**Files:** `server/lib/lanes.js`, `server/routes/lanes.js`, `server/lib/pty-run.js`, `server/lib/tmux.js` (`pasteText`), `server/lib/dashboard-runs.js`, `server/lib/router-apply.js`, `server/lib/ai-routers.js` (builtin label "Native"), `server/routes/run.js` (forward sandbox/approval/resumeLast/bypass), `bin/agenthub.js` (`lanes add --tool`).
- `VALID_TOOLS` ⇒ `aiTools.has`; lane creation on a disabled tool ⇒ 400 `EDISABLED`.
- `buildCatalogArgv(tool, {resumeLast, bypass, initialPrompt}, bin)` → `[bin, ...args, ...resume?, ...bypass?, ...prompt]`; `after-start` ⇒ `setTimeout(delayMs)` then `tmux.pasteText(id, prompt)` if the session still exists.
- Every spawn env carries `PATH: process.env.PATH`; catalog tools start by `detect().path` (fallback first `detect` name); `bypassEnv` merged when `bypass`.
- Codex: `bypass` ⇒ catalog codex bypass args, and `-s`/`-a` dropped.
- Unknown tool ⇒ `ENOTOOL` at spawn.
- router-apply: non-`routerCapable` accepts only native/builtin.
- [ ] Tests: argv per prompt mode, resume, bypass on/off, Codex bypass, Claude ignores bypass, after-start paste scheduling (fake timers), PATH in env, EDISABLED/EBADTOOL/not-installed allowed, router-apply generic, dashboard-runs any id.

### Task 5: Client data layer

**Files:** `client/src/lib/api.ts` (`aiTools.list/refresh/update`, `AiTool` type, `RunStartArgs.bypass`), `client/src/lib/types.ts` (`LaneTool = string`, drop `LANE_TOOL_LABEL`), create `client/src/hooks/useAiTools.ts` (`useAiTools(): {tools, default, byId, label(id), reload, loading}` — module-level shared cache + subscribers, refetch on focus), replace all `LANE_TOOL_LABEL` uses and the Workspace per-tool binary probes.

### Task 6: Settings → AI Tools section

**Files:** Create `client/src/components/settings/AiToolsSettings.tsx`; modify `client/src/pages/Settings.tsx` (TOC + section), i18n `settings.json` en/vi; hide Claude/Codex tabs while disabled (settings hub nav).
- [ ] Test `client/src/components/settings/__tests__/AiToolsSettings.test.tsx`: rows, toggle calls `update(id,{enabled})`, set default, refresh, available rows show only link.

### Task 7: Add lane + router row + run form

**Files:** `AddLaneModal.tsx` (Default / Other… select, empty state link), `LaneCard.tsx` `LaneRouterRow` ("Native (<label>)", router options disabled for non-routerCapable), `Workspace.tsx`, `RunSetup.tsx` (catalog form: resume, red bypass checkbox; Codex bypass), `LaneConsolePane.tsx`, i18n.
- [ ] Tests updated/added for Default/Other, disabled router option, resume + bypass on the catalog form, Codex bypass.

### Task 8: Docs + full verification

- CLAUDE.md (tool rule, bypass rule, router label, marker), AGENTS.md, docs/LANES.md, docs/API.md, docs/CLI.md, server/README.md, `npm run openapi:yaml`.
- `npm run test:server`, `cd client && NODE_ENV=test npx vitest run` (review snapshot diffs), `npx tsc --noEmit`, `bash skills/file-headers/scripts/check-headers.sh`.