pi-quests 0.3.0 → 0.5.0

package/src/quest/formatters.ts

@@ -1,35 +1,138 @@
+/**
+ * Error message design guidelines
+ *
+ * All error messages should follow a consistent three-part pattern:
+ *   1. PROBLEM — state what went wrong clearly and concisely
+ *   2. RULE    — explain the constraint or invariant that was violated
+ *   3. RECOVERY HINT — suggest the next valid action the caller can take
+ *
+ * Example:
+ *   "Quest [01] has incomplete steps. A parent quest can only be marked
+ *    done after all its steps are complete. Try toggling the steps first."
+ *
+ * Keep messages actionable. Agents should never be left guessing why something
+ * failed or what to do next.
+ */
+
 export function formatQuestList(
-  quests: { id: number; description: string; done: boolean }[],
+  quests: { id: string; description: string; done: boolean; parentId?: string }[],
 ): string {
   if (quests.length === 0) return "No quests.";
 
-  return quests.map((q, i) => `#${i + 1} [${q.done ? "x" : " "}] ${q.description}`).join("\n");
+  const lines: string[] = [];
+  let pos = 1;
+  for (const q of quests) {
+    if (q.parentId) {
+      lines.push(`   [${q.id}] [${q.done ? "x" : " "}] ${q.description}`);
+    } else {
+      lines.push(`#${pos} [${q.id}] [${q.done ? "x" : " "}] ${q.description}`);
+      pos++;
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatAddResult(q: { id: string; description: string }): string {
+  return `Added quest [${q.id}]: ${q.description}`;
+}
+
+export function formatBatchAddResult(added: { id: string; description: string }[]): string {
+  return `Added ${added.length} quests:\n${added.map((q) => `[${q.id}]: ${q.description}`).join("\n")}`;
+}
+
+export function formatToggleResult(id: string, done: boolean): string {
+  return `Quest [${id}] ${done ? "done" : "undone"}`;
+}
+
+export function formatUpdateResult(q: { id: string; description: string }): string {
+  return `Updated quest [${q.id}]: ${q.description}`;
+}
+
+export function formatDeleteResult(q: { id: string; description: string }): string {
+  return `Deleted quest [${q.id}]: ${q.description}`;
+}
+
+export function formatNotFound(id: string): string {
+  return `Quest [${id}] not found. IDs are random hex strings shown in brackets. Use the list action to see valid IDs.`;
+}
+
+export function formatBlockedBySteps(id: string): string {
+  return `Quest [${id}] has incomplete steps. A parent quest can only be marked done or deleted after all its steps are complete. Toggle the steps first, or delete them if they are no longer needed.`;
+}
+
+export function formatStepCannotHaveSteps(id: string): string {
+  return `Step [${id}] cannot have nested steps. The quest system only supports one level of nesting. Use a top-level quest as the parent instead.`;
+}
+
+export function formatEmptyDescriptionsError(): string {
+  return `Every description in a batch must be non-empty. Remove empty strings or split the batch into separate add calls.`;
 }
 
-export function formatAddResult(q: { id: number; description: string }): string {
-  return `Added quest #${q.id}: ${q.description}`;
+export function formatMissingDescriptionsError(action = "add"): string {
+  return `At least one description is required for the ${action} action. Provide a description string to create a quest.`;
 }
 
-export function formatBatchAddResult(added: { id: number; description: string }[]): string {
-  return `Added ${added.length} quests:\n${added.map((q) => `#${q.id}: ${q.description}`).join("\n")}`;
+export function formatIdRequiredError(action: string): string {
+  return `An id is required for the ${action} action. Use the list action to see valid quest IDs. IDs are the hex strings shown in square brackets.`;
+}
+
+export function formatDescriptionRequiredError(): string {
+  return `A description is required for the update action. Provide a non-empty string to update the quest.`;
+}
+
+export function formatTargetIdRequiredError(): string {
+  return `A targetId is required for the reorder action. Provide the hex ID of the quest to insert before.`;
+}
+
+export function formatReorderNotFoundError(): string {
+  return `Quest not found or is a step. Reorder only works on top-level quests. Use the list action to verify the ID and ensure it is a top-level quest.`;
+}
+
+export function formatParentNotFoundError(id: string): string {
+  return `Parent quest [${id}] not found. Use the list action to see valid parent IDs.`;
+}
+
+export function formatParentDoneError(id: string): string {
+  return `Cannot add a step to completed parent quest [${id}]. Steps can only be added to open parents. Reopen the parent first if you need to add more work.`;
+}
+
+export function formatUnknownActionError(action: string): string {
+  return `Unknown action: ${action}. Use the list action or check the tool schema for supported actions.`;
+}
+
+export function formatNothingToRevertError(): string {
+  return `Nothing to revert. The history is empty because no mutating actions have been performed yet.`;
+}
+
+export function formatReorderedQuestNotFoundError(): string {
+  return `Reordered quest not found. It may have been deleted or cleared since the reorder was recorded.`;
+}
+
+export function formatReparentResult(
+  q: { id: string; description: string },
+  parentId?: string,
+): string {
+  return parentId
+    ? `Moved quest [${q.id}] under [${parentId}]: ${q.description}`
+    : `Promoted quest [${q.id}] to top-level: ${q.description}`;
 }
 
-export function formatToggleResult(id: number, done: boolean): string {
-  return `Quest #${id} ${done ? "done" : "undone"}`;
+export function formatReparentTargetNotFoundError(id: string): string {
+  return `Target quest [${id}] not found. Use the list action to see valid parent IDs.`;
 }
 
-export function formatUpdateResult(q: { id: number; description: string }): string {
-  return `Updated quest #${q.id}: ${q.description}`;
+export function formatReparentTargetIsStepError(id: string): string {
+  return `Step [${id}] cannot be a parent. The quest system only supports one level of nesting. Use a top-level quest as the parent instead.`;
 }
 
-export function formatDeleteResult(q: { id: number; description: string }): string {
-  return `Deleted quest #${q.id}: ${q.description}`;
+export function formatReparentTargetDoneError(id: string): string {
+  return `Cannot reparent under completed parent [${id}]. Steps can only be added to open parents.`;
 }
 
-export function formatClearResult(count: number): string {
-  return `Cleared ${count} quests`;
+export function formatReparentDemoteHasStepsError(id: string): string {
+  return `Quest [${id}] has steps and cannot be demoted to a step. Delete or reparent its steps first.`;
 }
 
-export function formatNotFound(id: number): string {
-  return `Quest #${id} not found`;
+export function formatReparentSelfParentError(id: string): string {
+  return `Quest [${id}] cannot be its own parent. Choose a different parent ID.`;
 }

package/src/quest/tracker.ts

@@ -1,20 +1,8 @@
-export const COMPLEX_TASK_KEYWORDS = [
-  "implement",
-  "refactor",
-  "investigate",
-  "review",
-  "analyze",
-  "audit",
-  "plan",
-  "design",
-  "create",
-  "build",
-  "write",
-  "fix",
-] as const;
-
-const ACKNOWLEDGEMENT =
-  "ALWAYS acknowledge this reminder and create, update, or align on quests before making further tool calls.";
+import type { ResolvedConfig } from "../config.js";
+
+const ACKNOWLEDGEMENT = "Update your quest status before continuing.";
+
+type NudgeCandidate = { index: number; message: string };
 
 export class QuestUsageTracker {
   private totalToolCalls = 0;
@@ -22,6 +10,10 @@ export class QuestUsageTracker {
   private hasEverUsedQuestTool = false;
   private lastQuestToolTime = 0;
   private nudgedThisTurn = false;
+  private lastNudgeTime = 0;
+  private lastNudgeIndex = -1;
+
+  constructor(private readonly config: ResolvedConfig) {}
 
   onToolExecution(toolName: string): void {
     this.totalToolCalls++;
@@ -38,50 +30,118 @@ export class QuestUsageTracker {
     this.nudgedThisTurn = false;
   }
 
-  getNudge(activeQuestCount: number, latestPrompt?: string): string | undefined {
+  getNudge(
+    activeQuestCount: number,
+    latestPrompt?: string,
+    hasTopLevelQuestWithoutSubs?: boolean,
+  ): string | undefined {
     if (this.nudgedThisTurn) return undefined;
 
-    // 1. Initialization nudge
-    if (this.totalToolCalls >= 3 && !this.hasEverUsedQuestTool) {
+    const now = Date.now();
+    const cooldownMs = this.config.nudges.hintIntervalMinutes * 60 * 1000;
+    if (this.lastNudgeTime > 0 && now - this.lastNudgeTime < cooldownMs) {
+      return undefined;
+    }
+
+    const eligible = this.getEligibleNudges(
+      activeQuestCount,
+      latestPrompt,
+      hasTopLevelQuestWithoutSubs,
+    );
+
+    // Rotate priority: start checking from the nudge after the last one that fired
+    const rotated = [
+      ...eligible.filter((n) => n.index > this.lastNudgeIndex),
+      ...eligible.filter((n) => n.index <= this.lastNudgeIndex),
+    ];
+
+    const winner = rotated[0];
+    if (winner) {
       this.nudgedThisTurn = true;
-      return `QUEST REMINDER: You have made ${this.totalToolCalls} tool calls but have NEVER used the quest tool this session. USE the quest tool to initialize tracking and break your work into concrete steps. ${ACKNOWLEDGEMENT}`;
+      this.lastNudgeTime = now;
+      this.lastNudgeIndex = winner.index;
+      return winner.message;
     }
 
-    // 2. Complex-task entrypoint nudge
+    return undefined;
+  }
+
+  private getEligibleNudges(
+    activeQuestCount: number,
+    latestPrompt?: string,
+    hasTopLevelQuestWithoutSubs?: boolean,
+  ): NudgeCandidate[] {
+    const candidates: NudgeCandidate[] = [];
+
+    // 0. Initialization nudge
+    if (this.totalToolCalls >= this.config.nudges.toolCallThreshold && !this.hasEverUsedQuestTool) {
+      candidates.push({
+        index: 0,
+        message: `QUEST REMINDER: You have made ${this.totalToolCalls} tool calls but have NEVER used the quest tool this session. USE the quest tool to initialize tracking and break your work into concrete steps. ${ACKNOWLEDGEMENT}`,
+      });
+    }
+
+    // 1. Complex-task entrypoint nudge
     if (activeQuestCount === 0 && latestPrompt && this.isComplexPrompt(latestPrompt)) {
-      this.nudgedThisTurn = true;
-      return `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}`;
+      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}`,
+      });
     }
 
-    // 3. Time-based alignment nudge
+    // 2. Time-based alignment nudge
     if (
       this.hasEverUsedQuestTool &&
       this.lastQuestToolTime > 0 &&
-      this.consecutiveNonQuestToolCalls >= 3 &&
-      // 8 minutes without quest tool use
-      Date.now() - this.lastQuestToolTime >= 8 * 60 * 1000
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.timeBasedToolCallThreshold &&
+      Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
-      this.nudgedThisTurn = true;
-      return `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}`;
+      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}`,
+      });
     }
 
-    // 4. Zero-active sustained-work nudge
-    if (this.consecutiveNonQuestToolCalls >= 5 && activeQuestCount === 0) {
-      this.nudgedThisTurn = true;
-      return `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and there are 0 active quests. TRACK your work with specific, actionable quests. ${ACKNOWLEDGEMENT}`;
+    // 3. Zero-active sustained-work nudge
+    if (
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.zeroActiveToolCallThreshold &&
+      activeQuestCount === 0
+    ) {
+      candidates.push({
+        index: 3,
+        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and there are 0 active quests. TRACK your work with specific, actionable quests. ${ACKNOWLEDGEMENT}`,
+      });
+    }
+
+    // 4. Sub-quest suggestion nudge
+    if (
+      this.hasEverUsedQuestTool &&
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.stepSuggestionToolCallThreshold &&
+      activeQuestCount > 0 &&
+      hasTopLevelQuestWithoutSubs
+    ) {
+      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}`,
+      });
     }
 
     // 5. Stale-progress sustained-work nudge
-    if (this.consecutiveNonQuestToolCalls >= 10 && activeQuestCount > 0) {
-      this.nudgedThisTurn = true;
-      return `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. ${ACKNOWLEDGEMENT}`;
+    if (
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.staleProgressToolCallThreshold &&
+      activeQuestCount > 0
+    ) {
+      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}`,
+      });
     }
 
-    return undefined;
+    return candidates;
   }
 
   private isComplexPrompt(prompt: string): boolean {
     const lower = prompt.toLowerCase();
-    return COMPLEX_TASK_KEYWORDS.some((kw) => lower.includes(kw));
+    return this.config.nudges.complexTaskKeywords.some((kw) => lower.includes(kw));
   }
 }

package/src/quest/types.ts

@@ -11,6 +11,11 @@ export const QUEST_ACTIONS = {
   clear: "clear",
   reorder: "reorder",
   revert: "revert",
+  reparent: "reparent",
+  rules: "rules",
+  skill: "skill",
+  split: "split",
+  add_step: "add_step",
 } as const;
 
 export const QUEST_ACTION_VALUES = [
@@ -22,14 +27,22 @@ export const QUEST_ACTION_VALUES = [
   QUEST_ACTIONS.clear,
   QUEST_ACTIONS.reorder,
   QUEST_ACTIONS.revert,
+  QUEST_ACTIONS.reparent,
+  QUEST_ACTIONS.rules,
+  QUEST_ACTIONS.skill,
+  QUEST_ACTIONS.split,
+  QUEST_ACTIONS.add_step,
 ] as const;
 
 export type QuestActionType = (typeof QUEST_ACTION_VALUES)[number];
 
 export interface Quest {
-  id: number;
+  id: string;
   description: string;
-  additionalContext?: string;
   done: boolean;
   createdAt: number;
 }
+
+export interface Step extends Quest {
+  parentId: string;
+}

package/src/renderers/commands.ts

@@ -1,20 +1,22 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
-import type { Quest } from "../quest/types.js";
+import type { QuestLog } from "../quest/dataplane.js";
+import { formatQuestRow, formatStepSpacerLine } from "./quests.js";
 
 export class QuestListWidget {
   private cachedWidth?: number;
   private cachedLines?: string[];
   private page = 0;
-  private readonly pageSize = 10;
 
   constructor(
-    private quests: Quest[],
+    private questLog: QuestLog,
     private theme: Theme,
     private onClose: () => void,
+    private readonly config: ResolvedConfig,
   ) {
-    logger.debug("quests:widget", "create", { questCount: quests.length });
+    logger.debug("quests:widget", "create", { questCount: questLog.getAll().length });
   }
 
   handleInput(data: string): void {
@@ -37,7 +39,35 @@ export class QuestListWidget {
   }
 
   private get totalPages(): number {
-    return Math.max(1, Math.ceil(this.quests.length / this.pageSize));
+    const totalLines = this.buildQuestLines(0).length;
+    return Math.max(1, Math.ceil(totalLines / this.config.display.pageSize));
+  }
+
+  private buildQuestLines(width: number): string[] {
+    const th = this.theme;
+    const parents = this.questLog.getQuests();
+    const lines: string[] = [];
+
+    for (let i = 0; i < parents.length; i++) {
+      const parent = parents[i];
+      const steps = this.questLog.getSteps(parent.id);
+
+      const row = formatQuestRow(th, parent, this.config.ids.length, i + 1);
+      lines.push(width > 0 ? truncateToWidth(row, width) : row);
+
+      if (steps.length > 0) {
+        lines.push(formatStepSpacerLine(th, this.config.ids.length));
+
+        for (const step of steps) {
+          const stepRow = formatQuestRow(th, step, this.config.ids.length);
+          lines.push(width > 0 ? truncateToWidth(stepRow, width) : stepRow);
+        }
+
+        lines.push("");
+      }
+    }
+
+    return lines;
   }
 
   private nextPage(): void {
@@ -72,13 +102,14 @@ export class QuestListWidget {
       width,
       page: this.page,
       totalPages: this.totalPages,
-      totalQuests: this.quests.length,
+      totalQuests: this.questLog.getAll().length,
     });
 
     const th = this.theme;
     const lines: string[] = [];
-    const total = this.quests.length;
-    const doneCount = this.quests.filter((q) => q.done).length;
+    const allQuests = this.questLog.getAll();
+    const total = allQuests.length;
+    const doneCount = allQuests.filter((q) => q.done).length;
 
     // Top accent border
     lines.push(th.fg("accent", "─".repeat(width)));
@@ -91,7 +122,7 @@ export class QuestListWidget {
 
     lines.push("");
 
-    if (this.quests.length === 0) {
+    if (total === 0) {
       lines.push(
         truncateToWidth(
           `  ${th.fg("dim", "No active quests. Add one with /quests add <description>")}`,
@@ -100,7 +131,7 @@ export class QuestListWidget {
       );
     } else {
       // Mini progress bar
-      const barWidth = Math.min(width - 4, 24);
+      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));
@@ -108,20 +139,11 @@ export class QuestListWidget {
       lines.push(truncateToWidth(`  ${bar}  ${th.fg("muted", `${doneCount}/${total}`)}`, width));
       lines.push("");
 
-      const start = this.page * this.pageSize;
-      const pageQuests = this.quests.slice(start, start + this.pageSize);
-      for (let i = 0; i < pageQuests.length; i++) {
-        const q = pageQuests[i];
-        const pos = start + i + 1;
-        const marker = q.done ? th.fg("success", "  ✓ ") : th.fg("muted", "  ○ ");
-        const idStr = th.fg(q.done ? "dim" : "accent", `#${pos}`);
-        const desc = q.done
-          ? th.fg("dim", th.strikethrough(q.description))
-          : th.fg("text", q.description);
-        const row = `${marker}${idStr} ${desc}`;
-
-        lines.push(truncateToWidth(row, width));
-      }
+      const questLines = this.buildQuestLines(width);
+      const start = this.page * this.config.display.pageSize;
+      const pageLines = questLines.slice(start, start + this.config.display.pageSize);
+
+      lines.push(...pageLines);
 
       if (this.totalPages > 1) {
         const pageInfo = `  Page ${this.page + 1}/${this.totalPages}  ${th.fg("dim", "· Tab/Shift+Tab to navigate")}`;

package/src/renderers/quests.ts

@@ -0,0 +1,45 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { visibleWidth } from "@mariozechner/pi-tui";
+import type { Quest, Step } from "../quest/types.js";
+
+export function formatQuestRow(
+  theme: Theme,
+  q: Quest | Step,
+  idLength: number,
+  pos?: number,
+): string {
+  const isStep = "parentId" in q && q.parentId;
+
+  // position test is only relevant for quests, not steps
+  const posText = isStep ? "" : pos !== undefined ? `#${pos}` : "";
+  const posWidth = visibleWidth(posText);
+  const idText = `[${q.id}]`;
+
+  // spacing is added to keep text aligned
+  const spacing = " ".repeat(visibleWidth(`${16 ** idLength}`) - posWidth);
+  const idStr = `${theme.fg("muted", idText)} ${theme.fg(q.done ? "dim" : "accent", `${posText}`)}${spacing}`;
+
+  // for steps, use a different marker and indent
+  const markerNotDone = isStep ? theme.fg("muted", " └── ○ ") : theme.fg("muted", " ○ ");
+  const markerDone = isStep ? theme.fg("muted", " └── ✓ ") : theme.fg("success", " ✓ ");
+  const marker = q.done ? markerDone : markerNotDone;
+
+  // for steps, use dim text to contrast with the parent quests
+  const descColor = q.done || isStep ? "dim" : "text";
+  const desc = q.done
+    ? theme.fg(descColor, theme.strikethrough(q.description))
+    : theme.fg(descColor, q.description);
+
+  const line = `  ${idStr}${marker} ${desc}`;
+  return line;
+}
+
+export function formatStepSpacerLine(theme: Theme, idLength: number): string {
+  const idTextLength = visibleWidth(`${16 ** idLength}`);
+  // spacing for `[id](position string)`
+  const spacerStr = `${" ".repeat(idTextLength + 2)}${" ".repeat(idTextLength)}`;
+
+  const marker = theme.fg("muted", " │   ");
+
+  return `  ${spacerStr}${marker}`;
+}