@tekmidian/pai 0.9.4 → 0.9.5

package/dist/hooks/whisper-rules.mjs

@@ -5,6 +5,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 var WHISPER_FILE = join(homedir(), ".claude", "whisper-rules.md");
+var ADVISOR_FILE = join(homedir(), ".claude", "advisor-mode.json");
 function getWhisperRules() {
   if (existsSync(WHISPER_FILE)) {
     try {
@@ -15,11 +16,66 @@ function getWhisperRules() {
   }
   return "";
 }
+function getAdvisorGuidance() {
+  if (!existsSync(ADVISOR_FILE)) return "";
+  let config;
+  try {
+    config = JSON.parse(readFileSync(ADVISOR_FILE, "utf-8"));
+  } catch {
+    return "";
+  }
+  let mode = config.mode ?? "auto";
+  if (mode === "auto" && typeof config.weeklyBudgetPercent === "number") {
+    const pct = config.weeklyBudgetPercent;
+    if (pct < 70) mode = "normal";
+    else if (pct < 85) mode = "conservative";
+    else if (pct < 95) mode = "strict";
+    else mode = "critical";
+  }
+  if (config.forceModel) {
+    return `ADVISOR MODE: Use model "${config.forceModel}" for ALL subagents (Agent tool calls). This is a manual override.`;
+  }
+  switch (mode) {
+    case "normal":
+      return "";
+    // No constraints — use models freely
+    case "conservative":
+      return [
+        `ADVISOR MODE (conservative \u2014 weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "Use HAIKU for all subagents (Agent tool, model: haiku) unless the task explicitly requires deep reasoning.",
+        "Main context stays on the current model. Only escalate subagents to sonnet if haiku output quality is insufficient.",
+        "Prefer fewer, more focused subagent calls over many parallel ones."
+      ].join(" ");
+    case "strict":
+      return [
+        `ADVISOR MODE (strict \u2014 weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "Use HAIKU for ALL subagents without exception (Agent tool, model: haiku).",
+        "Minimize subagent spawning \u2014 do simple tasks directly in main context.",
+        "Only spawn subagents for genuinely independent parallel work.",
+        "Never spawn opus subagents."
+      ].join(" ");
+    case "critical":
+      return [
+        `ADVISOR MODE (critical \u2014 weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "MINIMIZE ALL TOKEN USAGE. Do NOT spawn subagents unless absolutely essential.",
+        "Work directly in main context. Keep responses concise.",
+        "Use haiku model if you must spawn a subagent.",
+        "Skip background research, parallel exploration, and spotchecks.",
+        "The user is near their weekly limit \u2014 every token counts."
+      ].join(" ");
+    default:
+      return "";
+  }
+}
 function main() {
+  const parts = [];
   const rules = getWhisperRules();
-  if (!rules) return;
+  if (rules) parts.push(rules);
+  const advisor = getAdvisorGuidance();
+  if (advisor) parts.push(advisor);
+  if (parts.length === 0) return;
   console.log(`<system-reminder>
-${rules}
+${parts.join("\n")}
 </system-reminder>`);
 }
 main();

package/dist/hooks/whisper-rules.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks/ts/user-prompt/whisper-rules.ts"],
-  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-rules.ts\n *\n * UserPromptSubmit hook that injects critical non-negotiable rules into every\n * prompt as a <system-reminder>. This ensures rules survive compaction \u2014 even\n * if CLAUDE.md content is lost during context compression, the whisper\n * re-injects the absolute rules on every single turn.\n *\n * Inspired by Letta's \"claude-subconscious\" whisper pattern.\n *\n * Rules are loaded from ~/.claude/whisper-rules.md if it exists,\n * otherwise falls back to hardcoded critical rules.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\n\nconst WHISPER_FILE = join(homedir(), \".claude\", \"whisper-rules.md\");\n\nfunction getWhisperRules(): string {\n  // User-managed whisper file \u2014 PAI provides the hook, user provides the rules\n  // Configure via /whisper skill or edit ~/.claude/whisper-rules.md directly\n  if (existsSync(WHISPER_FILE)) {\n    try {\n      const content = readFileSync(WHISPER_FILE, \"utf-8\").trim();\n      if (content) return content;\n    } catch { /* ignore read errors */ }\n  }\n\n  // No rules configured \u2014 silent (no injection)\n  return \"\";\n}\n\nfunction main() {\n  const rules = getWhisperRules();\n  if (!rules) return;\n\n  // Output as system-reminder \u2014 Claude Code injects this into the conversation\n  console.log(`<system-reminder>\n${rules}\n</system-reminder>`);\n}\n\nmain();\n"],
-  "mappings": ";;;AAgBA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AACrB,SAAS,eAAe;AAExB,IAAM,eAAe,KAAK,QAAQ,GAAG,WAAW,kBAAkB;AAElE,SAAS,kBAA0B;AAGjC,MAAI,WAAW,YAAY,GAAG;AAC5B,QAAI;AACF,YAAM,UAAU,aAAa,cAAc,OAAO,EAAE,KAAK;AACzD,UAAI,QAAS,QAAO;AAAA,IACtB,QAAQ;AAAA,IAA2B;AAAA,EACrC;AAGA,SAAO;AACT;AAEA,SAAS,OAAO;AACd,QAAM,QAAQ,gBAAgB;AAC9B,MAAI,CAAC,MAAO;AAGZ,UAAQ,IAAI;AAAA,EACZ,KAAK;AAAA,mBACY;AACnB;AAEA,KAAK;",
+  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-rules.ts\n *\n * UserPromptSubmit hook that injects:\n * 1. User-defined whisper rules from ~/.claude/whisper-rules.md\n * 2. Budget-aware model tiering guidance from ~/.claude/advisor-mode.json\n *\n * The advisor mode implements the \"advisor strategy\" pattern:\n * - Normal (budget < 70%): use any model freely\n * - Conservative (70-85%): prefer haiku for subagents, sonnet for main work\n * - Strict (85-95%): haiku only for subagents, main context stays on current model\n * - Critical (>95%): minimize all subagent spawning, essential work only\n *\n * Budget percentage is written by the statusline or manually to advisor-mode.json.\n * If the file doesn't exist, no advisor guidance is injected.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { homedir } from \"node:os\";\n\nconst WHISPER_FILE = join(homedir(), \".claude\", \"whisper-rules.md\");\nconst ADVISOR_FILE = join(homedir(), \".claude\", \"advisor-mode.json\");\n\nfunction getWhisperRules(): string {\n  if (existsSync(WHISPER_FILE)) {\n    try {\n      const content = readFileSync(WHISPER_FILE, \"utf-8\").trim();\n      if (content) return content;\n    } catch { /* ignore */ }\n  }\n  return \"\";\n}\n\ninterface AdvisorConfig {\n  weeklyBudgetPercent?: number;  // 0-100, written by statusline or manually\n  mode?: \"normal\" | \"conservative\" | \"strict\" | \"critical\" | \"auto\";\n  forceModel?: string;  // override: always use this model for subagents\n}\n\nfunction getAdvisorGuidance(): string {\n  if (!existsSync(ADVISOR_FILE)) return \"\";\n\n  let config: AdvisorConfig;\n  try {\n    config = JSON.parse(readFileSync(ADVISOR_FILE, \"utf-8\"));\n  } catch {\n    return \"\";\n  }\n\n  // Determine mode\n  let mode = config.mode ?? \"auto\";\n  if (mode === \"auto\" && typeof config.weeklyBudgetPercent === \"number\") {\n    const pct = config.weeklyBudgetPercent;\n    if (pct < 70) mode = \"normal\";\n    else if (pct < 85) mode = \"conservative\";\n    else if (pct < 95) mode = \"strict\";\n    else mode = \"critical\";\n  }\n\n  // Force model override\n  if (config.forceModel) {\n    return `ADVISOR MODE: Use model \"${config.forceModel}\" for ALL subagents (Agent tool calls). This is a manual override.`;\n  }\n\n  switch (mode) {\n    case \"normal\":\n      return \"\";  // No constraints \u2014 use models freely\n\n    case \"conservative\":\n      return [\n        `ADVISOR MODE (conservative \u2014 weekly budget at ${config.weeklyBudgetPercent ?? \"?\"}%):`,\n        \"Use HAIKU for all subagents (Agent tool, model: haiku) unless the task explicitly requires deep reasoning.\",\n        \"Main context stays on the current model. Only escalate subagents to sonnet if haiku output quality is insufficient.\",\n        \"Prefer fewer, more focused subagent calls over many parallel ones.\",\n      ].join(\" \");\n\n    case \"strict\":\n      return [\n        `ADVISOR MODE (strict \u2014 weekly budget at ${config.weeklyBudgetPercent ?? \"?\"}%):`,\n        \"Use HAIKU for ALL subagents without exception (Agent tool, model: haiku).\",\n        \"Minimize subagent spawning \u2014 do simple tasks directly in main context.\",\n        \"Only spawn subagents for genuinely independent parallel work.\",\n        \"Never spawn opus subagents.\",\n      ].join(\" \");\n\n    case \"critical\":\n      return [\n        `ADVISOR MODE (critical \u2014 weekly budget at ${config.weeklyBudgetPercent ?? \"?\"}%):`,\n        \"MINIMIZE ALL TOKEN USAGE. Do NOT spawn subagents unless absolutely essential.\",\n        \"Work directly in main context. Keep responses concise.\",\n        \"Use haiku model if you must spawn a subagent.\",\n        \"Skip background research, parallel exploration, and spotchecks.\",\n        \"The user is near their weekly limit \u2014 every token counts.\",\n      ].join(\" \");\n\n    default:\n      return \"\";\n  }\n}\n\nfunction main() {\n  const parts: string[] = [];\n\n  const rules = getWhisperRules();\n  if (rules) parts.push(rules);\n\n  const advisor = getAdvisorGuidance();\n  if (advisor) parts.push(advisor);\n\n  if (parts.length === 0) return;\n\n  console.log(`<system-reminder>\\n${parts.join(\"\\n\")}\\n</system-reminder>`);\n}\n\nmain();\n"],
+  "mappings": ";;;AAmBA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AACrB,SAAS,eAAe;AAExB,IAAM,eAAe,KAAK,QAAQ,GAAG,WAAW,kBAAkB;AAClE,IAAM,eAAe,KAAK,QAAQ,GAAG,WAAW,mBAAmB;AAEnE,SAAS,kBAA0B;AACjC,MAAI,WAAW,YAAY,GAAG;AAC5B,QAAI;AACF,YAAM,UAAU,aAAa,cAAc,OAAO,EAAE,KAAK;AACzD,UAAI,QAAS,QAAO;AAAA,IACtB,QAAQ;AAAA,IAAe;AAAA,EACzB;AACA,SAAO;AACT;AAQA,SAAS,qBAA6B;AACpC,MAAI,CAAC,WAAW,YAAY,EAAG,QAAO;AAEtC,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM,aAAa,cAAc,OAAO,CAAC;AAAA,EACzD,QAAQ;AACN,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,OAAO,QAAQ;AAC1B,MAAI,SAAS,UAAU,OAAO,OAAO,wBAAwB,UAAU;AACrE,UAAM,MAAM,OAAO;AACnB,QAAI,MAAM,GAAI,QAAO;AAAA,aACZ,MAAM,GAAI,QAAO;AAAA,aACjB,MAAM,GAAI,QAAO;AAAA,QACrB,QAAO;AAAA,EACd;AAGA,MAAI,OAAO,YAAY;AACrB,WAAO,4BAA4B,OAAO,UAAU;AAAA,EACtD;AAEA,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA;AAAA,IAET,KAAK;AACH,aAAO;AAAA,QACL,sDAAiD,OAAO,uBAAuB,GAAG;AAAA,QAClF;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,GAAG;AAAA,IAEZ,KAAK;AACH,aAAO;AAAA,QACL,gDAA2C,OAAO,uBAAuB,GAAG;AAAA,QAC5E;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,GAAG;AAAA,IAEZ,KAAK;AACH,aAAO;AAAA,QACL,kDAA6C,OAAO,uBAAuB,GAAG;AAAA,QAC9E;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,GAAG;AAAA,IAEZ;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,OAAO;AACd,QAAM,QAAkB,CAAC;AAEzB,QAAM,QAAQ,gBAAgB;AAC9B,MAAI,MAAO,OAAM,KAAK,KAAK;AAE3B,QAAM,UAAU,mBAAmB;AACnC,MAAI,QAAS,OAAM,KAAK,OAAO;AAE/B,MAAI,MAAM,WAAW,EAAG;AAExB,UAAQ,IAAI;AAAA,EAAsB,MAAM,KAAK,IAAI,CAAC;AAAA,mBAAsB;AAC1E;AAEA,KAAK;",
   "names": []
 }

package/dist/skills/Advisor/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: Advisor
+description: "Manage budget-aware advisor mode — control model tiering for subagents based on weekly usage. USE WHEN user says 'advisor', 'budget mode', 'set advisor', 'save budget', '/advisor', 'how much budget', OR wants to control model tiering for subagents."
+---
+
+## Advisor Mode Management
+
+USE WHEN user says 'advisor', 'budget mode', 'set advisor', 'save budget', '/advisor', 'how much budget', OR wants to control model tiering for subagents.
+
+Advisor mode controls which models subagents use, based on weekly budget consumption.
+
+### Configuration
+
+The config file is at `~/.claude/advisor-mode.json`:
+```json
+{
+  "weeklyBudgetPercent": 90,
+  "mode": "auto"
+}
+```
+
+### Usage
+
+- `/advisor` — show current mode and budget
+- `/advisor set <percent>` — set weekly budget percentage (triggers auto mode calculation)
+- `/advisor mode <normal|conservative|strict|critical>` — force a specific mode
+- `/advisor auto` — reset to auto mode (derives from weeklyBudgetPercent)
+- `/advisor force <model>` — force all subagents to use a specific model (haiku/sonnet/opus)
+- `/advisor reset` — remove the config file (no advisor guidance injected)
+
+### Mode Thresholds (auto mode)
+
+| Budget Used | Mode | Subagent Model | Behavior |
+|-------------|------|----------------|----------|
+| < 70% | normal | Any | No constraints |
+| 70-85% | conservative | Haiku preferred | Escalate to sonnet only if haiku insufficient |
+| 85-95% | strict | Haiku only | Minimize spawning, no opus subagents |
+| > 95% | critical | Haiku or none | Essential work only, minimize all token usage |
+
+### Workflow
+
+**Show current status:**
+Read `~/.claude/advisor-mode.json`. Display the mode, budget percentage, and what model constraints are active.
+
+**Update budget percentage:**
+The user reads their weekly budget from the statusline (e.g., "7d: 63% → Fr. 08:00").
+Write the percentage to `weeklyBudgetPercent` in the config file.
+If mode is "auto", the whisper hook will compute the appropriate tier.
+
+**Force a mode:**
+Set `mode` to the desired value. Overrides auto calculation.
+Useful when the user wants to be aggressive (normal) or cautious (strict) regardless of actual budget.
+
+**Force a model:**
+Set `forceModel` to "haiku", "sonnet", or "opus". ALL subagents will use this model.
+Useful for testing or when the user knows exactly what they want.
+
+### Integration
+
+The advisor config is read by the whisper-rules hook on every prompt. Changes take effect immediately — no restart needed. The guidance appears as an ADVISOR MODE line in the system-reminder alongside the whisper rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/src/hooks/ts/user-prompt/whisper-rules.ts

@@ -3,15 +3,18 @@
 /**
  * whisper-rules.ts
  *
- * UserPromptSubmit hook that injects critical non-negotiable rules into every
- * prompt as a <system-reminder>. This ensures rules survive compaction — even
- * if CLAUDE.md content is lost during context compression, the whisper
- * re-injects the absolute rules on every single turn.
+ * UserPromptSubmit hook that injects:
+ * 1. User-defined whisper rules from ~/.claude/whisper-rules.md
+ * 2. Budget-aware model tiering guidance from ~/.claude/advisor-mode.json
  *
- * Inspired by Letta's "claude-subconscious" whisper pattern.
+ * The advisor mode implements the "advisor strategy" pattern:
+ * - Normal (budget < 70%): use any model freely
+ * - Conservative (70-85%): prefer haiku for subagents, sonnet for main work
+ * - Strict (85-95%): haiku only for subagents, main context stays on current model
+ * - Critical (>95%): minimize all subagent spawning, essential work only
  *
- * Rules are loaded from ~/.claude/whisper-rules.md if it exists,
- * otherwise falls back to hardcoded critical rules.
+ * Budget percentage is written by the statusline or manually to advisor-mode.json.
+ * If the file doesn't exist, no advisor guidance is injected.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -19,29 +22,97 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 
 const WHISPER_FILE = join(homedir(), ".claude", "whisper-rules.md");
+const ADVISOR_FILE = join(homedir(), ".claude", "advisor-mode.json");
 
 function getWhisperRules(): string {
-  // User-managed whisper file — PAI provides the hook, user provides the rules
-  // Configure via /whisper skill or edit ~/.claude/whisper-rules.md directly
   if (existsSync(WHISPER_FILE)) {
     try {
       const content = readFileSync(WHISPER_FILE, "utf-8").trim();
       if (content) return content;
-    } catch { /* ignore read errors */ }
+    } catch { /* ignore */ }
   }
-
-  // No rules configured — silent (no injection)
   return "";
 }
 
+interface AdvisorConfig {
+  weeklyBudgetPercent?: number;  // 0-100, written by statusline or manually
+  mode?: "normal" | "conservative" | "strict" | "critical" | "auto";
+  forceModel?: string;  // override: always use this model for subagents
+}
+
+function getAdvisorGuidance(): string {
+  if (!existsSync(ADVISOR_FILE)) return "";
+
+  let config: AdvisorConfig;
+  try {
+    config = JSON.parse(readFileSync(ADVISOR_FILE, "utf-8"));
+  } catch {
+    return "";
+  }
+
+  // Determine mode
+  let mode = config.mode ?? "auto";
+  if (mode === "auto" && typeof config.weeklyBudgetPercent === "number") {
+    const pct = config.weeklyBudgetPercent;
+    if (pct < 70) mode = "normal";
+    else if (pct < 85) mode = "conservative";
+    else if (pct < 95) mode = "strict";
+    else mode = "critical";
+  }
+
+  // Force model override
+  if (config.forceModel) {
+    return `ADVISOR MODE: Use model "${config.forceModel}" for ALL subagents (Agent tool calls). This is a manual override.`;
+  }
+
+  switch (mode) {
+    case "normal":
+      return "";  // No constraints — use models freely
+
+    case "conservative":
+      return [
+        `ADVISOR MODE (conservative — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "Use HAIKU for all subagents (Agent tool, model: haiku) unless the task explicitly requires deep reasoning.",
+        "Main context stays on the current model. Only escalate subagents to sonnet if haiku output quality is insufficient.",
+        "Prefer fewer, more focused subagent calls over many parallel ones.",
+      ].join(" ");
+
+    case "strict":
+      return [
+        `ADVISOR MODE (strict — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "Use HAIKU for ALL subagents without exception (Agent tool, model: haiku).",
+        "Minimize subagent spawning — do simple tasks directly in main context.",
+        "Only spawn subagents for genuinely independent parallel work.",
+        "Never spawn opus subagents.",
+      ].join(" ");
+
+    case "critical":
+      return [
+        `ADVISOR MODE (critical — weekly budget at ${config.weeklyBudgetPercent ?? "?"}%):`,
+        "MINIMIZE ALL TOKEN USAGE. Do NOT spawn subagents unless absolutely essential.",
+        "Work directly in main context. Keep responses concise.",
+        "Use haiku model if you must spawn a subagent.",
+        "Skip background research, parallel exploration, and spotchecks.",
+        "The user is near their weekly limit — every token counts.",
+      ].join(" ");
+
+    default:
+      return "";
+  }
+}
+
 function main() {
+  const parts: string[] = [];
+
   const rules = getWhisperRules();
-  if (!rules) return;
+  if (rules) parts.push(rules);
+
+  const advisor = getAdvisorGuidance();
+  if (advisor) parts.push(advisor);
+
+  if (parts.length === 0) return;
 
-  // Output as system-reminder — Claude Code injects this into the conversation
-  console.log(`<system-reminder>
-${rules}
-</system-reminder>`);
+  console.log(`<system-reminder>\n${parts.join("\n")}\n</system-reminder>`);
 }
 
 main();