token-pilot 0.19.2 → 0.22.2

package/dist/cli/scan-agents.js

@@ -0,0 +1,227 @@
+/**
+ * Agent scanner + classifier (subtasks 3.2 + 3.3).
+ *
+ * Discovers agent .md files from three locations:
+ *   1. project .claude/agents/**\/*.md  (scope: 'project')
+ *   2. user   ~/.claude/agents/**\/*.md  (scope: 'user')
+ *   3. plugin-contributed agents         (scope: 'plugin')
+ *
+ * For each file: parses frontmatter, computes body hash, returns a ScannedAgent.
+ * Never throws — bad/unreadable files are skipped with a one-line stderr note.
+ * Symlinks pointing outside the scope's nominal root are skipped.
+ */
+import { readFile, lstat, realpath, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, resolve, basename } from "node:path";
+import { parseFrontmatter, parseToolsField, } from "./agent-frontmatter.js";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function sha256(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+/**
+ * Recursively list all *.md files under a directory.
+ * Returns absolute paths. Returns [] if the directory doesn't exist.
+ */
+async function listMdFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        const name = entry.name;
+        const fullPath = join(dir, name);
+        if (entry.isDirectory()) {
+            const nested = await listMdFiles(fullPath);
+            results.push(...nested);
+        }
+        else if (entry.isFile() && name.endsWith(".md")) {
+            results.push(fullPath);
+        }
+        // Skip symlinks entirely at this level — handled per-file below
+    }
+    return results;
+}
+/**
+ * Expand glob patterns (supporting only the trailing `*.md` form used for
+ * plugin cache paths). For patterns without wildcards the path is treated
+ * literally. Never throws.
+ */
+async function resolveGlobs(patterns) {
+    const results = [];
+    for (const pattern of patterns) {
+        if (!pattern.includes("*")) {
+            // Literal file path
+            try {
+                const stat = await lstat(pattern);
+                if (stat.isFile())
+                    results.push(resolve(pattern));
+            }
+            catch {
+                // ignore missing
+            }
+            continue;
+        }
+        // Only handle trailing `*.md` glob (the only form used for plugin dirs)
+        const starIdx = pattern.indexOf("*");
+        const dir = pattern.slice(0, starIdx);
+        const suffix = pattern.slice(starIdx + 1); // e.g. ".md"
+        let entries;
+        try {
+            entries = await readdir(dir.replace(/\/$/, ""), {
+                withFileTypes: true,
+                encoding: "utf-8",
+            });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = entry.name;
+            if (entry.isFile() && name.endsWith(suffix)) {
+                results.push(resolve(join(dir.replace(/\/$/, ""), name)));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Check whether filePath is a symlink that resolves outside of rootDir.
+ * Returns true if the file should be skipped.
+ */
+async function isSymlinkOutsideRoot(filePath, rootDir) {
+    let stat;
+    try {
+        stat = await lstat(filePath);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink())
+        return false;
+    try {
+        const real = await realpath(filePath);
+        const normalRoot = resolve(rootDir) + "/";
+        return !real.startsWith(normalRoot);
+    }
+    catch {
+        // If we can't resolve, skip it to be safe
+        return true;
+    }
+}
+/**
+ * Parse one agent file. Returns a ScannedAgent or null if the file should be
+ * skipped (parse failure, missing name, symlink outside root).
+ */
+async function parseAgentFile(filePath, scope, scopeRoot) {
+    // Symlink guard
+    if (await isSymlinkOutsideRoot(filePath, scopeRoot)) {
+        return null;
+    }
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        process.stderr.write(`token-pilot scan-agents: skipping ${filePath}: ${err instanceof Error ? err.message : err}\n`);
+        return null;
+    }
+    const { meta, body } = parseFrontmatter(content);
+    // Must have a name
+    const name = typeof meta.name === "string" && meta.name.trim()
+        ? meta.name.trim()
+        : basename(filePath, ".md");
+    // If body is empty AND no name in frontmatter AND no description, it's likely
+    // a file with no frontmatter at all — skip it
+    if (!meta.name && !meta.description && body === content) {
+        process.stderr.write(`token-pilot scan-agents: skipping ${filePath}: no frontmatter found\n`);
+        return null;
+    }
+    const tools = parseToolsField(meta.tools);
+    const description = typeof meta.description === "string" ? meta.description : "";
+    const bodyHash = sha256(body);
+    // blessed: check token_pilot.blessed === true (explicit marker, not substring)
+    const blessed = meta.token_pilot !== null &&
+        typeof meta.token_pilot === "object" &&
+        meta.token_pilot.blessed === true;
+    return {
+        name,
+        path: filePath,
+        scope,
+        tools,
+        description,
+        bodyHash,
+        blessed,
+    };
+}
+// ─── scanAgents ───────────────────────────────────────────────────────────────
+/**
+ * Scan all agent directories and return parsed ScannedAgent entries.
+ * Never throws.
+ */
+export async function scanAgents(opts) {
+    const results = [];
+    // 1. Project .claude/agents/
+    const projectAgentsDir = join(opts.projectRoot, ".claude", "agents");
+    const projectFiles = await listMdFiles(projectAgentsDir);
+    for (const filePath of projectFiles) {
+        const agent = await parseAgentFile(filePath, "project", projectAgentsDir);
+        if (agent)
+            results.push(agent);
+    }
+    // 2. User ~/.claude/agents/
+    const userAgentsDir = join(opts.homeDir, ".claude", "agents");
+    const userFiles = await listMdFiles(userAgentsDir);
+    for (const filePath of userFiles) {
+        const agent = await parseAgentFile(filePath, "user", userAgentsDir);
+        if (agent)
+            results.push(agent);
+    }
+    // 3. Plugin cache globs
+    const pluginFiles = await resolveGlobs(opts.pluginCacheGlob);
+    for (const filePath of pluginFiles) {
+        // For plugin files, use the file's parent directory as the scope root
+        const pluginRoot = resolve(filePath, "..");
+        const agent = await parseAgentFile(filePath, "plugin", pluginRoot);
+        if (agent)
+            results.push(agent);
+    }
+    return results;
+}
+// ─── classifyAgent ────────────────────────────────────────────────────────────
+const TP_PREFIX = "mcp__token-pilot__";
+function hasTokenPilotTool(tools) {
+    return tools.some((t) => t.startsWith(TP_PREFIX));
+}
+/**
+ * Classify an agent by its tools field.
+ *
+ * A — wildcard (tools: * | All tools) → already has MCP access
+ * A — explicit list that already contains mcp__token-pilot__* → already has access
+ * B — exclusion form where mcp__token-pilot__ is NOT excluded → has access
+ * C — explicit list without mcp__token-pilot__* → candidate for blessing
+ * C — exclusion form that explicitly excludes mcp__token-pilot__* → needs blessing
+ */
+export function classifyAgent(agent) {
+    const { tools } = agent;
+    switch (tools.kind) {
+        case "wildcard":
+            return "A";
+        case "exclusion": {
+            // If the exclusion list mentions mcp__token-pilot__ → agent lacks access
+            const excludesTP = tools.excluded.some((e) => e.startsWith(TP_PREFIX));
+            return excludesTP ? "C" : "B";
+        }
+        case "explicit": {
+            // If the explicit list already contains mcp__token-pilot__ → treat as A
+            if (hasTokenPilotTool(tools.tools))
+                return "A";
+            // Otherwise it's a restricted list → C candidate
+            return "C";
+        }
+    }
+}
+//# sourceMappingURL=scan-agents.js.map

package/dist/cli/stats.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Phase 6 subtask 6.3 — `token-pilot stats` CLI.
+ *
+ * Reads from `<projectRoot>/.token-pilot/hook-events.jsonl` and renders
+ * one of three views:
+ *   - default    : totals + top files by savedTokens
+ *   - --session  : events filtered to a single session_id (explicit arg
+ *                  or the most recent session in the log)
+ *   - --by-agent : events grouped by agent_type, sorted desc by savedTokens
+ *
+ * formatStats() is pure (events in → string out) so tests drive it
+ * directly without touching the filesystem.
+ */
+import { type HookEvent } from "../core/event-log.js";
+export interface StatsOptions {
+    /**
+     * `true` → pick the session_id of the most recent event.
+     * `string` → filter to that specific session_id.
+     * `undefined` → no session filter.
+     */
+    session?: boolean | string;
+    byAgent?: boolean;
+}
+/**
+ * Pure formatter. Takes the full event list and options; returns the
+ * rendered text block. Multi-line; no trailing newline.
+ */
+export declare function formatStats(events: HookEvent[], opts: StatsOptions): string;
+/**
+ * CLI entry: `token-pilot stats [--session[=<id>]] [--by-agent]`.
+ * Prints to stdout and returns exit code 0.
+ */
+export declare function handleStats(argv: string[], opts?: {
+    projectRoot?: string;
+}): Promise<number>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/cli/stats.js

@@ -0,0 +1,131 @@
+/**
+ * Phase 6 subtask 6.3 — `token-pilot stats` CLI.
+ *
+ * Reads from `<projectRoot>/.token-pilot/hook-events.jsonl` and renders
+ * one of three views:
+ *   - default    : totals + top files by savedTokens
+ *   - --session  : events filtered to a single session_id (explicit arg
+ *                  or the most recent session in the log)
+ *   - --by-agent : events grouped by agent_type, sorted desc by savedTokens
+ *
+ * formatStats() is pure (events in → string out) so tests drive it
+ * directly without touching the filesystem.
+ */
+import { loadEvents } from "../core/event-log.js";
+function sumSaved(events) {
+    return events.reduce((sum, e) => sum + e.savedTokens, 0);
+}
+function groupBy(events, keyOf) {
+    const out = new Map();
+    for (const e of events) {
+        const k = keyOf(e);
+        const bucket = out.get(k);
+        if (bucket)
+            bucket.push(e);
+        else
+            out.set(k, [e]);
+    }
+    return out;
+}
+function pad(label, width) {
+    return label.length >= width
+        ? label
+        : label + " ".repeat(width - label.length);
+}
+function pickMostRecentSession(events) {
+    if (events.length === 0)
+        return null;
+    let latest = events[0];
+    for (const e of events)
+        if (e.ts > latest.ts)
+            latest = e;
+    return latest.session_id;
+}
+/**
+ * Pure formatter. Takes the full event list and options; returns the
+ * rendered text block. Multi-line; no trailing newline.
+ */
+export function formatStats(events, opts) {
+    let scope = events;
+    let sessionLabel = null;
+    // --session filter
+    if (opts.session !== undefined) {
+        const target = opts.session === true ? pickMostRecentSession(events) : opts.session;
+        if (!target) {
+            return "No events yet.";
+        }
+        sessionLabel = target;
+        scope = events.filter((e) => e.session_id === target);
+        if (scope.length === 0) {
+            return `No events for session ${target}.`;
+        }
+    }
+    if (scope.length === 0) {
+        return "No events yet.";
+    }
+    const lines = [];
+    const total = sumSaved(scope);
+    const sessionSuffix = sessionLabel ? ` (session ${sessionLabel})` : "";
+    lines.push(`token-pilot stats${sessionSuffix} — ${scope.length} event${scope.length === 1 ? "" : "s"}, ~${total} tokens saved`);
+    if (opts.byAgent) {
+        // Group by agent_type (null → "main").
+        const groups = groupBy(scope, (e) => (e.agent_type ?? "main"));
+        const rows = [...groups.entries()]
+            .map(([agent, evs]) => ({
+            agent,
+            saved: sumSaved(evs),
+            count: evs.length,
+        }))
+            .sort((a, b) => b.saved - a.saved);
+        lines.push("");
+        lines.push("By agent:");
+        for (const r of rows) {
+            lines.push(`  ${pad(r.agent, 20)}  ${r.count.toString().padStart(4)}× events  ~${r.saved} tokens saved`);
+        }
+    }
+    else {
+        // Default view: top files by savedTokens.
+        const groups = groupBy(scope, (e) => e.file);
+        const rows = [...groups.entries()]
+            .map(([file, evs]) => ({
+            file,
+            saved: sumSaved(evs),
+            count: evs.length,
+        }))
+            .sort((a, b) => b.saved - a.saved)
+            .slice(0, 10);
+        lines.push("");
+        lines.push("Top files:");
+        for (const r of rows) {
+            lines.push(`  ${pad(r.file, 40)}  ${r.count.toString().padStart(3)}×  ~${r.saved} tokens saved`);
+        }
+    }
+    return lines.join("\n");
+}
+// ─── CLI wrapper ─────────────────────────────────────────────────────────────
+function parseFlag(argv, key) {
+    for (const a of argv) {
+        if (a === `--${key}`)
+            return true;
+        if (a.startsWith(`--${key}=`))
+            return a.slice(key.length + 3);
+    }
+    return undefined;
+}
+/**
+ * CLI entry: `token-pilot stats [--session[=<id>]] [--by-agent]`.
+ * Prints to stdout and returns exit code 0.
+ */
+export async function handleStats(argv, opts) {
+    const projectRoot = opts?.projectRoot ?? process.cwd();
+    const events = await loadEvents(projectRoot);
+    const session = parseFlag(argv, "session");
+    const byAgent = parseFlag(argv, "by-agent");
+    const rendered = formatStats(events, {
+        session: session === undefined ? undefined : session,
+        byAgent: byAgent === true,
+    });
+    process.stdout.write(rendered + "\n");
+    return 0;
+}
+//# sourceMappingURL=stats.js.map

package/dist/cli/unbless-agents.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reverse side of `bless-agents` (Phase 3 subtask 3.6).
+ *
+ * Walks `./.claude/agents/*.md` in the project, parses each file's
+ * frontmatter, and deletes only files that carry the explicit
+ * `token_pilot.blessed: true` marker. Files without that marker — user's
+ * own customised agents, other plugins' overrides — are left untouched.
+ *
+ * The function never throws out: every I/O failure is captured in the
+ * returned summary so the caller can surface one human-readable stderr
+ * message afterwards.
+ */
+export interface UnblessOptions {
+    /** Project root — .claude/agents is resolved relative to this. */
+    projectRoot: string;
+    /** Specific agent names (without ".md"). Ignored when `all` is true. */
+    names: string[];
+    /** When true, remove every blessed file regardless of `names`. */
+    all: boolean;
+}
+export interface UnblessSummary {
+    /** Count of files deleted. */
+    removed: number;
+    /** Count of files intentionally skipped (missing, not blessed, etc.). */
+    skipped: number;
+    /** Details for skipped entries; useful for stderr reporting. */
+    skipDetails: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+export declare function unblessAgents(opts: UnblessOptions): Promise<UnblessSummary>;
+//# sourceMappingURL=unbless-agents.d.ts.map

package/dist/cli/unbless-agents.js

@@ -0,0 +1,85 @@
+/**
+ * Reverse side of `bless-agents` (Phase 3 subtask 3.6).
+ *
+ * Walks `./.claude/agents/*.md` in the project, parses each file's
+ * frontmatter, and deletes only files that carry the explicit
+ * `token_pilot.blessed: true` marker. Files without that marker — user's
+ * own customised agents, other plugins' overrides — are left untouched.
+ *
+ * The function never throws out: every I/O failure is captured in the
+ * returned summary so the caller can surface one human-readable stderr
+ * message afterwards.
+ */
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { parseFrontmatter } from "./agent-frontmatter.js";
+function isBlessedMarker(meta) {
+    const tp = meta.token_pilot;
+    if (typeof tp !== "object" || tp === null)
+        return false;
+    return tp.blessed === true;
+}
+export async function unblessAgents(opts) {
+    const summary = { removed: 0, skipped: 0, skipDetails: [] };
+    const agentsDir = join(opts.projectRoot, ".claude", "agents");
+    let entries;
+    try {
+        entries = await readdir(agentsDir);
+    }
+    catch {
+        // No .claude/agents dir → nothing to do; treat as success.
+        return summary;
+    }
+    const files = entries.filter((f) => f.endsWith(".md"));
+    const filesByName = new Map(files.map((f) => [f.replace(/\.md$/, ""), f]));
+    const targetNames = opts.all
+        ? files.map((f) => f.replace(/\.md$/, ""))
+        : opts.names;
+    for (const name of targetNames) {
+        const fileName = filesByName.get(name);
+        if (!fileName) {
+            summary.skipped++;
+            summary.skipDetails.push({ name, reason: "not found" });
+            continue;
+        }
+        const fullPath = join(agentsDir, fileName);
+        let body;
+        try {
+            body = await readFile(fullPath, "utf-8");
+        }
+        catch {
+            summary.skipped++;
+            summary.skipDetails.push({ name, reason: "read error" });
+            continue;
+        }
+        let meta;
+        try {
+            ({ meta } = parseFrontmatter(body));
+        }
+        catch {
+            summary.skipped++;
+            summary.skipDetails.push({ name, reason: "malformed frontmatter" });
+            continue;
+        }
+        if (!isBlessedMarker(meta)) {
+            summary.skipped++;
+            summary.skipDetails.push({ name, reason: "no blessed marker" });
+            continue;
+        }
+        try {
+            await unlink(fullPath);
+            summary.removed++;
+        }
+        catch {
+            summary.skipped++;
+            summary.skipDetails.push({ name, reason: "delete failed" });
+        }
+    }
+    // Emit one human-readable stderr line when we actually removed something.
+    if (summary.removed > 0) {
+        const plural = summary.removed === 1 ? "agent" : "agents";
+        process.stderr.write(`[token-pilot] Unblessed ${summary.removed} ${plural}.\n`);
+    }
+    return summary;
+}
+//# sourceMappingURL=unbless-agents.js.map

package/dist/cli/uninstall-agents.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Phase 5 subtask 5.5 — uninstall tp-* agents.
+ *
+ * Removes only files in the target scope's `.claude/agents/` that have
+ * `token_pilot_body_hash` in their frontmatter. Files without the marker
+ * are user-owned and are never touched. Scope is required — no global
+ * default — to prevent accidental deletion from the wrong location.
+ *
+ * Symmetric to install-agents: separation of core (uninstallAgents) and
+ * CLI wrapper (handleUninstallAgents) mirrors the Phase 3 bless/unbless
+ * split.
+ */
+export type Scope = "user" | "project";
+export interface UninstallOptions {
+    scope: Scope;
+    projectRoot: string;
+    homeDir: string;
+}
+export interface UninstallResult {
+    removed: string[];
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    targetDir: string;
+}
+export declare function uninstallAgents(opts: UninstallOptions): Promise<UninstallResult>;
+/**
+ * CLI entry: `token-pilot uninstall-agents --scope=user|project`.
+ * Returns the exit code (0 success, 1 error).
+ */
+export declare function handleUninstallAgents(argv: string[], opts?: {
+    homeDir?: string;
+    projectRoot?: string;
+}): Promise<number>;
+//# sourceMappingURL=uninstall-agents.d.ts.map

package/dist/cli/uninstall-agents.js

@@ -0,0 +1,117 @@
+/**
+ * Phase 5 subtask 5.5 — uninstall tp-* agents.
+ *
+ * Removes only files in the target scope's `.claude/agents/` that have
+ * `token_pilot_body_hash` in their frontmatter. Files without the marker
+ * are user-owned and are never touched. Scope is required — no global
+ * default — to prevent accidental deletion from the wrong location.
+ *
+ * Symmetric to install-agents: separation of core (uninstallAgents) and
+ * CLI wrapper (handleUninstallAgents) mirrors the Phase 3 bless/unbless
+ * split.
+ */
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseFrontmatter } from "./agent-frontmatter.js";
+function targetDirFor(opts) {
+    const root = opts.scope === "user" ? opts.homeDir : opts.projectRoot;
+    return join(root, ".claude", "agents");
+}
+function hasTpHashMarker(meta) {
+    const h = meta.token_pilot_body_hash;
+    return typeof h === "string" && h.length > 0;
+}
+export async function uninstallAgents(opts) {
+    const target = targetDirFor(opts);
+    const result = {
+        removed: [],
+        skipped: [],
+        targetDir: target,
+    };
+    let entries;
+    try {
+        entries = await readdir(target);
+    }
+    catch {
+        // Target dir missing → nothing to do.
+        return result;
+    }
+    const tpFiles = entries.filter((f) => f.endsWith(".md") && f.startsWith("tp-"));
+    for (const entry of tpFiles) {
+        const name = entry.replace(/\.md$/, "");
+        const fullPath = join(target, entry);
+        let md;
+        try {
+            md = await readFile(fullPath, "utf-8");
+        }
+        catch {
+            result.skipped.push({ name, reason: "read failed" });
+            continue;
+        }
+        let meta;
+        try {
+            ({ meta } = parseFrontmatter(md));
+        }
+        catch {
+            result.skipped.push({ name, reason: "malformed frontmatter" });
+            continue;
+        }
+        if (!hasTpHashMarker(meta)) {
+            result.skipped.push({
+                name,
+                reason: "not installed by token-pilot (no token_pilot_body_hash)",
+            });
+            continue;
+        }
+        try {
+            await unlink(fullPath);
+            result.removed.push(name);
+        }
+        catch {
+            result.skipped.push({ name, reason: "delete failed" });
+        }
+    }
+    return result;
+}
+// ─── CLI wrapper ─────────────────────────────────────────────────────────────
+function parseFlag(argv, key) {
+    for (const a of argv) {
+        if (a === `--${key}`)
+            return "true";
+        if (a.startsWith(`--${key}=`))
+            return a.slice(key.length + 3);
+    }
+    return undefined;
+}
+/**
+ * CLI entry: `token-pilot uninstall-agents --scope=user|project`.
+ * Returns the exit code (0 success, 1 error).
+ */
+export async function handleUninstallAgents(argv, opts) {
+    const scopeArg = parseFlag(argv, "scope");
+    if (scopeArg !== "user" && scopeArg !== "project") {
+        process.stderr.write("Usage: token-pilot uninstall-agents --scope=user|project\n");
+        return 1;
+    }
+    const result = await uninstallAgents({
+        scope: scopeArg,
+        projectRoot: opts?.projectRoot ?? process.cwd(),
+        homeDir: opts?.homeDir ?? homedir(),
+    });
+    if (result.removed.length > 0) {
+        const plural = result.removed.length === 1 ? "agent" : "agents";
+        process.stderr.write(`[token-pilot] Removed ${result.removed.length} ${plural} from ${result.targetDir}.\n`);
+    }
+    if (result.skipped.length > 0) {
+        process.stderr.write(`[token-pilot] Skipped ${result.skipped.length}:\n`);
+        for (const s of result.skipped) {
+            process.stderr.write(`  - ${s.name}: ${s.reason}\n`);
+        }
+    }
+    if (result.removed.length === 0 && result.skipped.length === 0) {
+        process.stderr.write(`[token-pilot] No tp-* agents found in ${result.targetDir}.\n`);
+    }
+    return 0;
+}
+//# sourceMappingURL=uninstall-agents.js.map

package/dist/config/defaults.d.ts

@@ -1,3 +1,3 @@
-import type { TokenPilotConfig } from '../types.js';
+import type { TokenPilotConfig } from "../types.js";
 export declare const DEFAULT_CONFIG: TokenPilotConfig;
 //# sourceMappingURL=defaults.d.ts.map