token-pilot 0.19.1 → 0.22.2

package/dist/templates/agent-builder.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Phase 4 subtask 4.3 — agent composer.
+ *
+ * Composes a final agent markdown by splicing three source parts:
+ *   1. `templates/agents/tp-NAME.md` — frontmatter + role block (source of truth)
+ *   2. `templates/agents/_shared-preamble.md` — MCP-first contract
+ *   3. `templates/agents/_response-contract.md` — output discipline
+ *
+ * Deliberately uses a regex split instead of parseFrontmatter/writeFrontmatter
+ * so the frontmatter block is preserved **byte-for-byte** — no YAML re-
+ * serialisation that could reorder keys or change quoting.
+ *
+ * This is a pure in-memory transformation. No files are written by this
+ * module; Phase 5 install-agents is the only writer.
+ */
+/**
+ * Pure string-to-string composer.
+ *
+ * @param source   Content of `tp-NAME.md` (frontmatter + role block).
+ * @param shared   Content of `_shared-preamble.md`.
+ * @param contract Content of `_response-contract.md`.
+ * @returns Composed agent body with exactly one frontmatter block, the
+ *   shared preamble immediately after it, the role block next, and the
+ *   response contract last. Ends with a single trailing newline.
+ * @throws if the source has no recognisable frontmatter delimiter pair.
+ */
+export declare function composeAgent(source: string, shared: string, contract: string): string;
+/**
+ * File-system wrapper around composeAgent. Reads the three parts from
+ * disk and returns the composed string. Does not write anything.
+ */
+export declare function composeFromFiles(sourcePath: string, sharedPath: string, contractPath: string): string;
+export interface ComposedAgent {
+    /** Agent name (file basename without `.md`). */
+    name: string;
+    /** Composed markdown ready to be written to `.claude/agents/<name>.md`. */
+    composed: string;
+}
+/**
+ * Scans `templatesDir` for `tp-*.md` files and composes each of them,
+ * using `_shared-preamble.md` and `_response-contract.md` from the same
+ * directory. Files starting with `_` are excluded.
+ *
+ * Returns an empty array if `templatesDir` contains no `tp-*.md` files
+ * (including when the directory is missing, to keep CLI invocations
+ * safe on fresh checkouts).
+ */
+export declare function composeAll(templatesDir: string): ComposedAgent[];
+//# sourceMappingURL=agent-builder.d.ts.map

package/dist/templates/agent-builder.js

@@ -0,0 +1,104 @@
+/**
+ * Phase 4 subtask 4.3 — agent composer.
+ *
+ * Composes a final agent markdown by splicing three source parts:
+ *   1. `templates/agents/tp-NAME.md` — frontmatter + role block (source of truth)
+ *   2. `templates/agents/_shared-preamble.md` — MCP-first contract
+ *   3. `templates/agents/_response-contract.md` — output discipline
+ *
+ * Deliberately uses a regex split instead of parseFrontmatter/writeFrontmatter
+ * so the frontmatter block is preserved **byte-for-byte** — no YAML re-
+ * serialisation that could reorder keys or change quoting.
+ *
+ * This is a pure in-memory transformation. No files are written by this
+ * module; Phase 5 install-agents is the only writer.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const FRONTMATTER_RE = /^(---\r?\n[\s\S]*?\r?\n---\r?\n)([\s\S]*)$/;
+/**
+ * Pure string-to-string composer.
+ *
+ * @param source   Content of `tp-NAME.md` (frontmatter + role block).
+ * @param shared   Content of `_shared-preamble.md`.
+ * @param contract Content of `_response-contract.md`.
+ * @returns Composed agent body with exactly one frontmatter block, the
+ *   shared preamble immediately after it, the role block next, and the
+ *   response contract last. Ends with a single trailing newline.
+ * @throws if the source has no recognisable frontmatter delimiter pair.
+ */
+export function composeAgent(source, shared, contract) {
+    const m = source.match(FRONTMATTER_RE);
+    if (!m) {
+        throw new Error("composeAgent: source has no frontmatter block (expected ---\\n...\\n---\\n at start)");
+    }
+    const [, frontmatter, roleBlock] = m;
+    return (frontmatter +
+        "\n" +
+        shared.trim() +
+        "\n\n" +
+        roleBlock.trim() +
+        "\n\n" +
+        contract.trim() +
+        "\n");
+}
+/**
+ * File-system wrapper around composeAgent. Reads the three parts from
+ * disk and returns the composed string. Does not write anything.
+ */
+export function composeFromFiles(sourcePath, sharedPath, contractPath) {
+    const source = readFileSync(sourcePath, "utf-8");
+    const shared = readFileSync(sharedPath, "utf-8");
+    const contract = readFileSync(contractPath, "utf-8");
+    return composeAgent(source, shared, contract);
+}
+/**
+ * Scans `templatesDir` for `tp-*.md` files and composes each of them,
+ * using `_shared-preamble.md` and `_response-contract.md` from the same
+ * directory. Files starting with `_` are excluded.
+ *
+ * Returns an empty array if `templatesDir` contains no `tp-*.md` files
+ * (including when the directory is missing, to keep CLI invocations
+ * safe on fresh checkouts).
+ */
+export function composeAll(templatesDir) {
+    let entries;
+    try {
+        entries = readdirSync(templatesDir);
+    }
+    catch {
+        return [];
+    }
+    const sharedPath = join(templatesDir, "_shared-preamble.md");
+    const contractPath = join(templatesDir, "_response-contract.md");
+    let shared;
+    let contract;
+    try {
+        shared = readFileSync(sharedPath, "utf-8");
+        contract = readFileSync(contractPath, "utf-8");
+    }
+    catch {
+        // Missing parts → caller gets nothing; Phase 5 can surface a friendly
+        // error. We never throw out of the bulk path.
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        if (entry.startsWith("_"))
+            continue;
+        if (!entry.startsWith("tp-"))
+            continue;
+        const name = entry.replace(/\.md$/, "");
+        try {
+            const source = readFileSync(join(templatesDir, entry), "utf-8");
+            results.push({ name, composed: composeAgent(source, shared, contract) });
+        }
+        catch {
+            // Skip unreadable / malformed source; Phase 5 may log.
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=agent-builder.js.map

package/dist/types.d.ts

@@ -1,8 +1,17 @@
 /**
  * Core domain types for Token Pilot.
  */
-export type SymbolKind = 'function' | 'class' | 'method' | 'property' | 'variable' | 'type' | 'interface' | 'enum' | 'constant' | 'namespace';
-export type Visibility = 'public' | 'private' | 'protected' | 'default';
+/**
+ * Hook enforcement mode.
+ * - 'off': PreToolUse hook is inert (no advisory, no deny).
+ * - 'advisory': hook emits a short tip but does not block Read.
+ * - 'deny-enhanced': hook denies oversized code Reads and returns a structural
+ *   summary inside permissionDecisionReason. Default from v0.20; preserves
+ *   v0.19 deny-behaviour while upgrading the message quality.
+ */
+export type HookMode = "off" | "advisory" | "deny-enhanced";
+export type SymbolKind = "function" | "class" | "method" | "property" | "variable" | "type" | "interface" | "enum" | "constant" | "namespace";
+export type Visibility = "public" | "private" | "protected" | "default";
 export interface FileStructure {
     path: string;
     language: string;
@@ -62,7 +71,7 @@ export interface ContextEntry {
     symbolNames?: string[];
 }
 export interface LoadedRegion {
-    type: 'structure' | 'symbol' | 'range' | 'full';
+    type: "structure" | "symbol" | "range" | "full";
     symbolName?: string;
     startLine: number;
     endLine: number;
@@ -104,6 +113,17 @@ export interface TokenPilotConfig {
         interceptRead: boolean;
         autoInstall: boolean;
         denyThreshold: number;
+        mode: HookMode;
+        /**
+         * When true, hook auto-lowers denyThreshold as session burns through
+         * adaptiveBudgetTokens. Opt-in — default false keeps v0.20 behaviour.
+         */
+        adaptiveThreshold: boolean;
+        /**
+         * Reference budget (in saved-token units from hook-events.jsonl) used
+         * to compute burn fraction. Defaults to a rough 100k proxy.
+         */
+        adaptiveBudgetTokens: number;
     };
     context: {
         estimateTokens: boolean;
@@ -118,7 +138,7 @@ export interface TokenPilotConfig {
         actionableHints: boolean;
     };
     contextMode: {
-        enabled: boolean | 'auto';
+        enabled: boolean | "auto";
         adviseDelegation: boolean;
         largeNonCodeThreshold: number;
     };
@@ -140,6 +160,20 @@ export interface TokenPilotConfig {
         compactionCallThreshold: number;
         compactionTokenThreshold: number;
     };
+    sessionStart: {
+        enabled: boolean;
+        showStats: boolean;
+        maxReminderTokens: number;
+    };
+    agents: {
+        /** Scope of last `install-agents` run, null until first install. */
+        scope: "user" | "project" | null;
+        /**
+         * Emit a one-time stderr reminder at MCP startup if no tp-* agents
+         * are installed. Can also be suppressed by env TOKEN_PILOT_NO_AGENT_REMINDER=1.
+         */
+        reminder: boolean;
+    };
     ignore: string[];
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,87 +1,89 @@
-{
-  "name": "token-pilot",
-  "version": "0.19.1",
-  "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "token-pilot": "dist/index.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "start.sh",
-    ".claude-plugin/",
-    ".mcp.json",
-    "skills/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "claude",
-    "claude-code",
-    "cursor",
-    "codex",
-    "cline",
-    "ai-coding",
-    "llm-tools",
-    "token-savings",
-    "token-reduction",
-    "context-window",
-    "context-optimization",
-    "ast",
-    "code-reading",
-    "code-navigation",
-    "smart-read",
-    "developer-tools",
-    "tree-sitter"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Digital-Threads/token-pilot.git"
-  },
-  "homepage": "https://github.com/Digital-Threads/token-pilot#readme",
-  "bugs": {
-    "url": "https://github.com/Digital-Threads/token-pilot/issues"
-  },
-  "mcpName": "io.github.Digital-Threads/token-pilot",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "chokidar": "^4.0.3"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "peerDependencies": {
-    "ast-index": ">=0.1.0"
-  },
-  "peerDependenciesMeta": {
-    "ast-index": {
-      "optional": true
-    }
-  },
-  "optionalDependencies": {
-    "@ast-grep/cli": "^0.41.0"
-  }
-}
+{
+  "name": "token-pilot",
+  "version": "0.22.2",
+  "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "token-pilot": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/agents/*.md",
+    "start.sh",
+    ".claude-plugin/",
+    ".mcp.json",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "build": "tsc && node scripts/build-agents.mjs",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "bench:hook": "node scripts/bench-hook.mjs",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "cline",
+    "ai-coding",
+    "llm-tools",
+    "token-savings",
+    "token-reduction",
+    "context-window",
+    "context-optimization",
+    "ast",
+    "code-reading",
+    "code-navigation",
+    "smart-read",
+    "developer-tools",
+    "tree-sitter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Threads/token-pilot.git"
+  },
+  "homepage": "https://github.com/Digital-Threads/token-pilot#readme",
+  "bugs": {
+    "url": "https://github.com/Digital-Threads/token-pilot/issues"
+  },
+  "mcpName": "io.github.Digital-Threads/token-pilot",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "chokidar": "^4.0.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "ast-index": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "ast-index": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@ast-grep/cli": "^0.41.0"
+  }
+}

package/skills/stats/SKILL.md

@@ -1,8 +1,19 @@
 ---
 name: stats
-description: Show Token Pilot session analytics — token savings, per-tool breakdown, top files
+description: Show Token Pilot session analytics — token savings, per-tool breakdown, top files, per-agent grouping
 command: stats
 user_invocable: true
 ---
 
-Call the `session_analytics` MCP tool from the token-pilot server to display the current session's token savings report. Show the output to the user as-is.
+Two entry points:
+
+1. **In-session rich summary (MCP tool).** Call the `session_analytics` MCP tool from the token-pilot server to display the current session's token savings with per-tool breakdown. Show the output to the user as-is.
+
+2. **CLI shortcut (works without a running MCP server).** When the user explicitly asks for a specific view, or when the MCP tool is unavailable, invoke:
+
+   - `token-pilot stats` — totals + top files by savedTokens
+   - `token-pilot stats --session` — totals for the most recent session
+   - `token-pilot stats --session=<id>` — totals for a specific session_id
+   - `token-pilot stats --by-agent` — savings grouped by agent_type (tp-run, tp-onboard, …, or "main" for the top-level session)
+
+The CLI reads `.token-pilot/hook-events.jsonl`, so it only shows data for qualifying Reads that were intercepted by the hook (not raw MCP tool calls — those live in session-analytics).