pi-quests 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-17
+
+- feat: add footer quest progress indicator with configurable icon
+- fix: quest list widget cache invalidation
+
+## [0.5.1] - 2026-04-17
+
+- fix: add context signals and calibrate nudge thresholds
+
 ## [0.5.0] - 2026-04-14
 
 - feat: add reparent action to promote, demote, or move quests and steps with validation and revert support

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.5.0](https://img.shields.io/badge/version-0.5.0-blue)](CHANGELOG.md)
+[![version 0.6.0](https://img.shields.io/badge/version-0.6.0-blue)](CHANGELOG.md)
 [![MIT license](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
 [![pi extension](https://img.shields.io/badge/pi-extension-purple)](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quests",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A quest-log for your pi. Keep your agent on track, one quest at a time.",
   "type": "module",
   "keywords": [
@@ -32,8 +32,10 @@
     "LICENSE.md"
   ],
   "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
     "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*"
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
@@ -49,6 +51,6 @@
     "style": "biome check ./src ./test",
     "style:fix": "biome check --write --unsafe --no-errors-on-unmatched ./src ./test",
     "format": "biome format --write --no-errors-on-unmatched ./src ./test",
-    "prepublishOnly": "npm run typecheck && npm test"
+    "prepublishOnly": "npx tsc --noEmit && npx vitest run"
   }
 }

package/src/commands/handler.ts

@@ -8,7 +8,7 @@ import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
 import type { QuestAction, QuestLog } from "../quest/dataplane.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
-import { QuestListWidget } from "../renderers/commands.js";
+import { invalidateQuestListWidget, QuestListWidget } from "../renderers/commands.js";
 import { CHANGELOG_PATH, getVersion } from "../version.js";
 import { reverseChangelog } from "./changelog.js";
 import { type ParsedArgs, parseQuestArgs } from "./parse-args.js";
@@ -73,7 +73,12 @@ export function openQuestList(
   );
 }
 
-export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog, config: ResolvedConfig) {
+export function createQuestsHandler(
+  pi: ExtensionAPI,
+  questLog: QuestLog,
+  config: ResolvedConfig,
+  onMutate?: (ctx: ExtensionCommandContext) => void,
+) {
   return async function handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
     logger.debug("quests:cmd", "handler", { args, hasUI: ctx.hasUI });
 
@@ -144,6 +149,8 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog, config
         const result = questLog.execute(action);
 
         logger.debug("quests:cmd", parsed.action, { success: result.success });
+        invalidateQuestListWidget();
+        onMutate?.(ctx);
         ctx.ui.notify(result.message, result.success ? "info" : "error");
         return;
       }

package/src/config.ts

@@ -5,7 +5,7 @@ import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 export interface ResolvedConfig {
   ids: { length: number };
-  display: { pageSize: number; progressBarMaxWidth: number };
+  display: { pageSize: number; progressBarMaxWidth: number; icon: string };
   nudges: {
     toolCallThreshold: number;
     hintIntervalMinutes: number;
@@ -23,28 +23,25 @@ export const DEFAULT_COMPLEX_TASK_KEYWORDS = [
   "implement",
   "refactor",
   "investigate",
-  "review",
   "analyze",
   "audit",
-  "plan",
   "design",
-  "create",
-  "build",
-  "write",
   "fix",
+  "plan",
+  "build",
 ] as const;
 
 export const DEFAULT_FAKE_DONE_PATTERN = String.raw`\s[-\u2013\u2014]\s*(DONE|COMPLETED|FINISHED)$|\s[([](DONE|COMPLETED|FINISHED)[)\]]$`;
 
 export const DEFAULT_CONFIG: ResolvedConfig = {
   ids: { length: 2 },
-  display: { pageSize: 10, progressBarMaxWidth: 24 },
+  display: { pageSize: 10, progressBarMaxWidth: 24, icon: "󰣏" },
   nudges: {
     toolCallThreshold: 8,
     hintIntervalMinutes: 4,
-    timeBasedToolCallThreshold: 5,
+    timeBasedToolCallThreshold: 8,
     zeroActiveToolCallThreshold: 8,
-    staleProgressToolCallThreshold: 16,
+    staleProgressToolCallThreshold: 12,
     stepSuggestionToolCallThreshold: 10,
     complexTaskKeywords: [...DEFAULT_COMPLEX_TASK_KEYWORDS],
   },
@@ -117,6 +114,7 @@ export function getConfig(ctx: Pick<ExtensionContext, "cwd">): ResolvedConfig {
       pageSize: user.display?.pageSize ?? DEFAULT_CONFIG.display.pageSize,
       progressBarMaxWidth:
         user.display?.progressBarMaxWidth ?? DEFAULT_CONFIG.display.progressBarMaxWidth,
+      icon: user.display?.icon ?? DEFAULT_CONFIG.display.icon,
     },
     nudges: {
       toolCallThreshold: user.nudges?.toolCallThreshold ?? DEFAULT_CONFIG.nudges.toolCallThreshold,

package/src/index.ts

@@ -4,11 +4,12 @@ import type { KeyId } from "@mariozechner/pi-tui";
 import { createQuestsHandler, openQuestList } from "./commands/handler.js";
 import { DEFAULT_CONFIG, getConfig, type ResolvedConfig } from "./config.js";
 import { logger } from "./logger.js";
-import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "./prompts.js";
+import { QUEST_PROMPT_GATE } from "./prompts.js";
 import { QuestLog } from "./quest/dataplane.js";
 import { formatQuestList } from "./quest/formatters.js";
 import { QuestUsageTracker } from "./quest/tracker.js";
 import { questChangelogRenderer } from "./renderers/changelog.js";
+import { QuestStatusWidget } from "./renderers/status.js";
 import { registerQuestTool } from "./tools/handler.js";
 
 /**
@@ -25,6 +26,7 @@ export default function (pi: ExtensionAPI): void {
   let questLog = new QuestLog();
   let tracker = new QuestUsageTracker(DEFAULT_CONFIG);
   let config: ResolvedConfig = DEFAULT_CONFIG;
+  let statusWidget = new QuestStatusWidget(DEFAULT_CONFIG.display.icon);
 
   const shortcutKey = getConfig({ cwd: process.cwd() }).shortcuts?.openQuests ?? "ctrl+shift+l";
   logger.debug("quests:shortcut", "register", { key: shortcutKey });
@@ -47,23 +49,33 @@ export default function (pi: ExtensionAPI): void {
     config = getConfig(ctx);
     questLog = new QuestLog(config);
     tracker = new QuestUsageTracker(config);
+    statusWidget = new QuestStatusWidget(config.display.icon);
     questLog.reconstructFromSession(ctx);
+    statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
 
     registerQuestTool(pi, questLog, config);
 
-    const questsHandler = createQuestsHandler(pi, questLog, config);
+    const questsHandler = createQuestsHandler(pi, questLog, config, (ctx) => {
+      statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
+    });
     pi.registerCommand("quests", {
       description: "Quest commands: /quests [help] to see usage",
       handler: questsHandler,
     });
   });
 
-  pi.on("session_tree", async (_event, ctx) => questLog.reconstructFromSession(ctx));
+  pi.on("session_tree", async (_event, ctx) => {
+    questLog.reconstructFromSession(ctx);
+    statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
+  });
 
   pi.on("turn_start", async () => tracker.clearTurnNudge());
 
-  pi.on("tool_execution_end", async (event) => {
+  pi.on("tool_execution_end", async (event, ctx) => {
     tracker.onToolExecution(event.toolName);
+    if (event.toolName === "quest") {
+      statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
+    }
   });
 
   pi.on("context", async (event) => {
@@ -79,7 +91,12 @@ export default function (pi: ExtensionAPI): void {
     const hasTopLevelQuestWithoutSubs = activeTopLevel.some(
       (q) => !allQuests.some((step) => (step as { parentId?: string }).parentId === q.id),
     );
-    const nudge = tracker.getNudge(activeQuestCount, latestPrompt, hasTopLevelQuestWithoutSubs);
+    const nudge = tracker.getNudge(
+      activeQuestCount,
+      allQuests,
+      latestPrompt,
+      hasTopLevelQuestWithoutSubs,
+    );
 
     const fakeDoneRegex = new RegExp(config.validation.fakeDonePattern, "i");
     const fakeDone = questLog.getAll().find((q) => !q.done && fakeDoneRegex.test(q.description));
@@ -106,7 +123,8 @@ export default function (pi: ExtensionAPI): void {
       const list = formatQuestList(quests);
       reminder = `Active quests (${remaining}/${quests.length}):\n${list}\n\nKeep quest progress updated as you work.`;
     } else {
-      reminder = `${QUEST_PROMPT_REMINDER.join("\n")}\n\nBefore adding any independent quests, clear any previously completed quests from the log to keep it focused on current work.`;
+      reminder =
+        "No active quests. Use the quest tool to track your work. Use action: 'skill' for usage documentation.";
     }
 
     return {

package/src/prompts.ts

@@ -9,22 +9,16 @@ export function getQuestSkillDocument(): string {
 }
 
 export const QUEST_PROMPT_REMINDER = [
-  "Use the quest tool VERY frequently to track tasks, plans, and progress throughout the conversation.",
-  "Before reading files, running commands, or making edits, ensure the current work is tracked as specific, actionable quests.",
-  "Do not create a single vague quest for broad requests. Break them into concrete, independent steps.",
-  "When the user gives a plan or a list of tasks, add them as quests immediately.",
-  "When reading a skill file, implementation plan, or protocol document that contains numbered steps or checklists, add those steps as quests immediately so they are tracked, and reorder them as needed in the quest log.",
-  "It is critical that you toggle quests to done as soon as you complete them. Do NOT batch completions.",
-  "ALWAYS use the toggle action to mark a quest done. NEVER use the update action to append 'DONE', '- DONE', or any completion marker to a quest description.",
-  "ALWAYS use steps to break down a complex quest into smaller steps. To create a step, use the `split` action with the parent quest's hex ID. Use steps for multi-step tasks, minion delegations, or when a quest has more than one distinct deliverable.",
-  "A parent quest cannot be toggled done until all of its steps are completed. Steps cannot be reordered independently.",
-  "Before delegating to a minion, add a quest for the delegated task.",
-  "As work evolves, use the reorder action to reflect changes in priority",
-  "For reorder, provide the targetId (the hex ID of the quest to insert before).",
-  "If you are unsure what to do next, use the list action to check active quests.",
-  "Always use the hex ID shown in brackets (e.g. 0a, ff, 44e1, f712a) for toggle, update, delete, and reorder actions.",
-  "When you need to understand the quest system, rules, or best practices, use the quest tool with action: 'skill' or action: 'rules' rather than reading documentation files.",
+  "Use the quest tool VERY frequently to track tasks, plans, and progress.",
+  "Before reading files or making edits, ensure work is tracked as specific, actionable quests.",
+  "Break broad requests into concrete, independent quests. Use split to break quests into steps for multi-step tasks. When the user gives a list of tasks, add them as quests immediately.",
+  "Toggle quests done as you complete them. Do NOT batch completions.",
+  "ALWAYS use the toggle action for completion. NEVER append completion markers via update.",
+  "A parent quest cannot be toggled done until all its steps are complete.",
+  "Always use the hex ID shown in brackets (e.g. 0a, ff) for actions, never the positional number.",
+  "When reading a skill file, plan, or protocol with numbered steps, add those steps as quests immediately.",
+  "Use the quest tool with action: 'skill' for complete usage documentation, patterns, and best practices.",
 ] as const;
 
 export const QUEST_PROMPT_GATE =
-  "Before reading files, running commands, or making edits, ALWAYS ensure the current work is tracked as specific, actionable quests. ALWAYS break broad requests into concrete steps.";
+  "Before reading files, running commands, or making edits, ALWAYS ensure the current work is tracked as specific, actionable quests.\nALWAYS breakdown broad quests into smaller steps.";

package/src/quest/tracker.ts

@@ -1,7 +1,20 @@
 import type { ResolvedConfig } from "../config.js";
+import { logger } from "../logger.js";
+import type { Quest } from "./types.js";
 
 const ACKNOWLEDGEMENT = "Update your quest status before continuing.";
 
+function formatActiveQuests(allQuests: Quest[], limit = 3): string {
+  const active = allQuests.filter((q) => !q.done);
+  if (active.length === 0) return "";
+
+  const shown = active.slice(0, limit);
+  const lines = shown.map((q) => `  [${q.id}]: ${q.description}`);
+  if (active.length > limit) lines.push(`  ... and ${active.length - limit} more`);
+
+  return `\nActive quests:\n${lines.join("\n")}`;
+}
+
 type NudgeCandidate = { index: number; message: string };
 
 export class QuestUsageTracker {
@@ -32,23 +45,38 @@ export class QuestUsageTracker {
 
   getNudge(
     activeQuestCount: number,
+    allQuests: Quest[],
     latestPrompt?: string,
     hasTopLevelQuestWithoutSubs?: boolean,
   ): string | undefined {
-    if (this.nudgedThisTurn) return undefined;
+    if (this.nudgedThisTurn) {
+      logger.debug("quests:tracker", "nudge-suppressed", { reason: "turn-limit" });
+      return undefined;
+    }
 
     const now = Date.now();
     const cooldownMs = this.config.nudges.hintIntervalMinutes * 60 * 1000;
     if (this.lastNudgeTime > 0 && now - this.lastNudgeTime < cooldownMs) {
+      logger.debug("quests:tracker", "nudge-suppressed", {
+        reason: "cooldown",
+        elapsed: now - this.lastNudgeTime,
+        cooldownMs,
+      });
       return undefined;
     }
 
     const eligible = this.getEligibleNudges(
       activeQuestCount,
+      allQuests,
       latestPrompt,
       hasTopLevelQuestWithoutSubs,
     );
 
+    logger.debug("quests:tracker", "nudge-candidates", {
+      eligible: eligible.length,
+      indices: eligible.map((c) => c.index),
+    });
+
     // Rotate priority: start checking from the nudge after the last one that fired
     const rotated = [
       ...eligible.filter((n) => n.index > this.lastNudgeIndex),
@@ -59,6 +87,11 @@ export class QuestUsageTracker {
     if (winner) {
       this.nudgedThisTurn = true;
       this.lastNudgeTime = now;
+
+      logger.debug("quests:tracker", "nudge-fired", {
+        winner: winner.index,
+        rotatedFrom: this.lastNudgeIndex,
+      });
       this.lastNudgeIndex = winner.index;
       return winner.message;
     }
@@ -68,6 +101,7 @@ export class QuestUsageTracker {
 
   private getEligibleNudges(
     activeQuestCount: number,
+    allQuests: Quest[],
     latestPrompt?: string,
     hasTopLevelQuestWithoutSubs?: boolean,
   ): NudgeCandidate[] {
@@ -85,7 +119,7 @@ export class QuestUsageTracker {
     if (activeQuestCount === 0 && latestPrompt && this.isComplexPrompt(latestPrompt)) {
       candidates.push({
         index: 1,
-        message: `QUEST REMINDER: Your latest prompt appears to be a complex task, but there are 0 active quests. USE the quest tool to break this into concrete, trackable steps. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: Your latest prompt is a complex task, but there are 0 active quests. USE the quest tool to break this into concrete, trackable steps. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -96,9 +130,10 @@ export class QuestUsageTracker {
       this.consecutiveNonQuestToolCalls >= this.config.nudges.timeBasedToolCallThreshold &&
       Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
+      const questContext = formatActiveQuests(allQuests);
       candidates.push({
         index: 2,
-        message: `QUEST REMINDER: It has been a while since your last quest tool use and ${this.consecutiveNonQuestToolCalls} tools have been called since then. ALIGN on quest status before continuing. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: It has been a while since your last quest tool use and ${this.consecutiveNonQuestToolCalls} tools have been called since then. ALIGN on quest status before continuing.${questContext} ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -122,18 +157,21 @@ export class QuestUsageTracker {
     ) {
       candidates.push({
         index: 4,
-        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and have active top-level quests without steps. Use the \`split\` action to break down complex tasks into smaller, trackable steps. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and have active top-level quests without steps. Consider the quest complexity and use the \`split\` action to break them into smaller steps and track progress. ${ACKNOWLEDGEMENT}`,
       });
     }
 
-    // 5. Stale-progress sustained-work nudge
+    // 5. Stale-progress sustained-work nudge (with time-gate)
     if (
       this.consecutiveNonQuestToolCalls >= this.config.nudges.staleProgressToolCallThreshold &&
-      activeQuestCount > 0
+      activeQuestCount > 0 &&
+      this.lastQuestToolTime > 0 &&
+      Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
+      const questContext = formatActiveQuests(allQuests);
       candidates.push({
         index: 5,
-        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool despite having active quests.\nUPDATE your quest progress to reflect current status.\nALWAYS use steps to break down a quest into smaller steps, and to group related tasks together. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool despite having active quests. UPDATE your quest progress to reflect current status.${questContext} ${ACKNOWLEDGEMENT}`,
       });
     }
 

package/src/renderers/commands.ts

@@ -5,6 +5,12 @@ import { logger } from "../logger.js";
 import type { QuestLog } from "../quest/dataplane.js";
 import { formatQuestRow, formatStepSpacerLine } from "./quests.js";
 
+let activeQuestListWidget: QuestListWidget | undefined;
+
+export function invalidateQuestListWidget(): void {
+  activeQuestListWidget?.invalidate();
+}
+
 export class QuestListWidget {
   private cachedWidth?: number;
   private cachedLines?: string[];
@@ -17,12 +23,14 @@ export class QuestListWidget {
     private readonly config: ResolvedConfig,
   ) {
     logger.debug("quests:widget", "create", { questCount: questLog.getAll().length });
+    activeQuestListWidget = this;
   }
 
   handleInput(data: string): void {
     logger.debug("quests:widget", "handleInput", { data });
     if (matchesKey(data, Key.escape) || data === "q" || data === "Q") {
       logger.debug("quests:widget", "close");
+      activeQuestListWidget = undefined;
       this.onClose();
       return;
     }
@@ -134,7 +142,7 @@ export class QuestListWidget {
       const barWidth = Math.min(width - 4, this.config.display.progressBarMaxWidth);
       const filled = Math.round((doneCount / total) * barWidth);
       const empty = barWidth - filled;
-      const bar = th.fg("success", "█".repeat(filled)) + th.fg("dim", "░".repeat(empty));
+      const bar = th.fg("success", "▰".repeat(filled)) + th.fg("dim", "▱".repeat(empty));
 
       lines.push(truncateToWidth(`  ${bar}  ${th.fg("muted", `${doneCount}/${total}`)}`, width));
       lines.push("");

package/src/renderers/status.ts

@@ -0,0 +1,34 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { QuestLog } from "../quest/dataplane.js";
+
+export class QuestStatusWidget {
+  private readonly key = "pi-quests";
+  private readonly barWidth = 5;
+
+  constructor(private readonly icon: string) {}
+
+  update(
+    questLog: QuestLog,
+    ui: { setStatus(key: string, text: string | undefined): void },
+    theme: Theme,
+  ): void {
+    const all = questLog.getAll();
+    const total = all.length;
+    const done = all.filter((q) => q.done).length;
+
+    const text = this.formatStatus(total, done, theme);
+    ui.setStatus(this.key, text);
+  }
+
+  private formatStatus(total: number, done: number, theme: Theme): string | undefined {
+    if (total === 0) {
+      return undefined;
+    }
+
+    const filled = Math.round((done / total) * this.barWidth);
+    const empty = this.barWidth - filled;
+    const bar = theme.fg("success", "▰".repeat(filled)) + theme.fg("muted", "▱".repeat(empty));
+
+    return `${theme.fg("accent", this.icon)} ${bar} ${theme.fg("dim", `${done}/${total}`)}`;
+  }
+}

package/src/tools/handler.ts

@@ -14,6 +14,7 @@ const SPLIT_DISPLAY_ACTIONS = [
   QUEST_ACTIONS.revert,
 ] as const;
 
+import { invalidateQuestListWidget } from "../renderers/commands.js";
 import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
 import { createQuestParams, type QuestParamsType } from "./params.js";
 
@@ -96,6 +97,7 @@ function runTool(
   action: QuestAction,
 ): AgentToolResult<unknown> {
   const result = questLog.execute(action);
+  invalidateQuestListWidget();
   logger.debug("quests:tool", "execute-complete", { toolCallId, success: result.success });
 
   const displayQuests = SPLIT_DISPLAY_ACTIONS.includes(
@@ -134,7 +136,7 @@ export function registerQuestTool(
       "When you need to understand quests, steps, rules, or best practices, use action: 'skill' or action: 'rules'.",
     promptSnippet:
       "Manage quests and steps, or retrieve quest rules and best practices via skill/rules",
-    promptGuidelines: [...QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
+    promptGuidelines: [QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
     parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
       questToolExecute(questLog, toolCallId, params),