pi-quests 0.1.0 → 0.3.0

package/src/quest/dataplane.ts

@@ -0,0 +1,430 @@
+import type { AgentToolResult, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { logger } from "../logger.js";
+import {
+  formatBatchAddResult,
+  formatDeleteResult,
+  formatNotFound,
+  formatQuestList,
+  formatToggleResult,
+  formatUpdateResult,
+} from "./formatters.js";
+import { QUEST_ACTIONS, type Quest } from "./types.js";
+
+export type HistoryEntry =
+  | { type: typeof QUEST_ACTIONS.add; id: number }
+  | { type: typeof QUEST_ACTIONS.toggle; id: number }
+  | { type: typeof QUEST_ACTIONS.update; id: number; previousDescription: string }
+  | { type: typeof QUEST_ACTIONS.delete; quest: Quest; index: number }
+  | {
+      type: typeof QUEST_ACTIONS.clear;
+      previousQuests: Quest[];
+      previousNextId: number;
+      all: false;
+    }
+  | { type: typeof QUEST_ACTIONS.clear; quests: Quest[]; nextId: number; all: true }
+  | { type: typeof QUEST_ACTIONS.reorder; quest: Quest; oldIndex: number; previousIds: number[] };
+
+export type QuestAction =
+  | { type: typeof QUEST_ACTIONS.add; descriptions?: string[] }
+  | { type: typeof QUEST_ACTIONS.list }
+  | { type: typeof QUEST_ACTIONS.toggle; id?: number }
+  | { type: typeof QUEST_ACTIONS.update; id?: number; description?: string }
+  | { type: typeof QUEST_ACTIONS.delete; id?: number }
+  | { type: typeof QUEST_ACTIONS.clear; all?: boolean }
+  | { type: typeof QUEST_ACTIONS.reorder; id?: number; targetIndex?: number }
+  | { type: typeof QUEST_ACTIONS.revert };
+
+export type QuestOperationResult = { success: boolean; message: string; quest?: Quest };
+
+/**
+ * In-memory quest data plane.
+ *
+ * Holds quest state, mutation history, and exposes `execute()` as the
+ * single entry point for all adapter layers (commands, tools, etc.).
+ */
+export class QuestLog {
+  private quests: Quest[] = [];
+  private nextId = 1;
+  private history: HistoryEntry[] = [];
+  private undoHandlers: {
+    [K in HistoryEntry["type"]]: (entry: Extract<HistoryEntry, { type: K }>) => {
+      success: boolean;
+      message: string;
+    };
+  } = {
+    [QUEST_ACTIONS.add]: (entry) => {
+      this.quests = this.quests.filter((q) => q.id !== entry.id);
+
+      const maxId = this.quests.reduce((max, q) => Math.max(max, q.id), 0);
+      this.nextId = Math.max(maxId + 1, entry.id);
+
+      logger.debug("quests:state", "revert-add", { id: entry.id, total: this.quests.length });
+      return { success: true, message: `Reverted add quest #${entry.id}` };
+    },
+    [QUEST_ACTIONS.toggle]: (entry) => {
+      const quest = this.quests.find((q) => q.id === entry.id);
+
+      if (quest) {
+        quest.done = !quest.done;
+        logger.debug("quests:state", "revert-toggle", { id: entry.id, done: quest.done });
+        return { success: true, message: `Reverted toggle for quest #${entry.id}` };
+      }
+
+      logger.debug("quests:state", "revert-toggle-not-found", { id: entry.id });
+      return { success: false, message: `Quest #${entry.id} not found` };
+    },
+    [QUEST_ACTIONS.update]: (entry) => {
+      const quest = this.quests.find((q) => q.id === entry.id);
+      if (quest) {
+        quest.description = entry.previousDescription;
+        logger.debug("quests:state", "revert-update", { id: entry.id });
+        return { success: true, message: `Reverted update for quest #${entry.id}` };
+      }
+
+      logger.debug("quests:state", "revert-update-not-found", { id: entry.id });
+      return { success: false, message: `Quest #${entry.id} not found` };
+    },
+    [QUEST_ACTIONS.delete]: (entry) => {
+      this.quests.splice(entry.index, 0, entry.quest);
+
+      logger.debug("quests:state", "revert-delete", {
+        id: entry.quest.id,
+        index: entry.index,
+        total: this.quests.length,
+      });
+      return { success: true, message: `Reverted delete for quest #${entry.quest.id}` };
+    },
+    [QUEST_ACTIONS.clear]: (entry) => {
+      if ("previousQuests" in entry) {
+        const restoredCount = entry.previousQuests.length - this.quests.length;
+        this.quests = [...entry.previousQuests];
+        this.nextId = entry.previousNextId;
+
+        return {
+          success: true,
+          message: `Reverted clear (${restoredCount} quests restored)`,
+        };
+      }
+
+      this.quests = [...entry.quests];
+      this.nextId = entry.nextId;
+
+      return { success: true, message: `Reverted clear (${entry.quests.length} quests restored)` };
+    },
+    [QUEST_ACTIONS.reorder]: (entry) => {
+      const currentIndex = this.quests.indexOf(entry.quest);
+      if (currentIndex === -1) return { success: false, message: "Reordered quest not found" };
+
+      this.quests.splice(currentIndex, 1);
+      this.quests.splice(entry.oldIndex, 0, entry.quest);
+      for (let i = 0; i < this.quests.length; i++) {
+        this.quests[i].id = entry.previousIds[i];
+      }
+
+      this.nextId = Math.max(...entry.previousIds, 0) + 1;
+      return { success: true, message: `Reverted reorder for quest #${entry.quest.id}` };
+    },
+  };
+
+  getAll(): Quest[] {
+    return [...this.quests];
+  }
+
+  getNextId(): number {
+    return this.nextId;
+  }
+
+  add(description: string, additionalContext?: string): Quest {
+    const quest: Quest = {
+      id: this.nextId++,
+      description,
+      additionalContext,
+      done: false,
+      createdAt: Date.now(),
+    };
+
+    this.quests.push(quest);
+    this.history.push({ type: QUEST_ACTIONS.add, id: quest.id });
+
+    logger.debug("quests:state", QUEST_ACTIONS.add, {
+      id: quest.id,
+      description,
+      total: this.quests.length,
+    });
+    return quest;
+  }
+
+  toggle(id: number): Quest | undefined {
+    const quest = this.quests.find((q) => q.id === id);
+    if (!quest) {
+      logger.debug("quests:state", "toggle-not-found", { id });
+      return undefined;
+    }
+
+    quest.done = !quest.done;
+    this.history.push({ type: QUEST_ACTIONS.toggle, id });
+
+    logger.debug("quests:state", QUEST_ACTIONS.toggle, {
+      id,
+      done: quest.done,
+      total: this.quests.length,
+    });
+    return quest;
+  }
+
+  update(id: number, description: string): Quest | undefined {
+    const quest = this.quests.find((q) => q.id === id);
+    if (!quest) {
+      logger.debug("quests:state", "update-not-found", { id });
+      return undefined;
+    }
+
+    this.history.push({ type: QUEST_ACTIONS.update, id, previousDescription: quest.description });
+    quest.description = description;
+
+    logger.debug("quests:state", QUEST_ACTIONS.update, {
+      id,
+      description,
+      total: this.quests.length,
+    });
+    return quest;
+  }
+
+  delete(id: number): Quest | undefined {
+    const index = this.quests.findIndex((q) => q.id === id);
+    if (index === -1) {
+      logger.debug("quests:state", "delete-not-found", { id });
+      return undefined;
+    }
+
+    const [quest] = this.quests.splice(index, 1);
+    this.history.push({ type: QUEST_ACTIONS.delete, quest, index });
+
+    logger.debug("quests:state", QUEST_ACTIONS.delete, { id, index, total: this.quests.length });
+    return quest;
+  }
+
+  clear(all = false): number {
+    if (!all) {
+      const done = this.quests.filter((q) => q.done);
+      const previousQuests = this.quests.map((q) => ({ ...q }));
+      const previousNextId = this.nextId;
+      this.quests = this.quests.filter((q) => !q.done);
+      for (let i = 0; i < this.quests.length; i++) {
+        this.quests[i].id = i + 1;
+      }
+      this.nextId = this.quests.length + 1;
+      this.history.push({
+        type: QUEST_ACTIONS.clear,
+        previousQuests,
+        previousNextId,
+        all: false,
+      });
+      logger.debug("quests:state", QUEST_ACTIONS.clear, { count: done.length, all });
+      return done.length;
+    }
+    const count = this.quests.length;
+    this.history.push({
+      type: QUEST_ACTIONS.clear,
+      quests: [...this.quests],
+      nextId: this.nextId,
+      all: true,
+    });
+    this.quests = [];
+    this.nextId = 1;
+    logger.debug("quests:state", QUEST_ACTIONS.clear, { count, all });
+    return count;
+  }
+
+  reorder(id: number, targetIndex: number): Quest | undefined {
+    const idx = this.quests.findIndex((q) => q.id === id);
+    if (idx === -1) {
+      logger.debug("quests:state", "reorder-not-found", { id });
+      return undefined;
+    }
+
+    const previousIds = this.quests.map((q) => q.id);
+    const [quest] = this.quests.splice(idx, 1);
+    this.quests.splice(targetIndex, 0, quest);
+    for (let i = 0; i < this.quests.length; i++) {
+      this.quests[i].id = i + 1;
+    }
+
+    this.nextId = this.quests.length + 1;
+    this.history.push({ type: QUEST_ACTIONS.reorder, quest, oldIndex: idx, previousIds });
+    logger.debug("quests:state", QUEST_ACTIONS.reorder, {
+      id: quest.id,
+      targetIndex,
+      total: this.quests.length,
+    });
+
+    return quest;
+  }
+
+  revert(): QuestOperationResult {
+    const entry = this.history.pop();
+    if (!entry) {
+      logger.debug("quests:state", "revert-empty");
+      return { success: false, message: "Nothing to revert" };
+    }
+
+    logger.debug("quests:state", "revert", { type: entry.type });
+
+    const handler = this.undoHandlers[entry.type];
+    if (handler) {
+      return handler(entry as never);
+    }
+
+    logger.debug("quests:state", "revert-unknown", { type: (entry as { type: string }).type });
+    return { success: false, message: "Unknown history entry" };
+  }
+
+  /**
+   * Execute a quest action and return a presentation-ready result.
+   * This is the primary API for all adapter layers (commands, tools).
+   */
+  execute(action: QuestAction): QuestOperationResult {
+    switch (action.type) {
+      case QUEST_ACTIONS.add: {
+        if (action.descriptions && action.descriptions.length > 0) {
+          if (action.descriptions.some((d) => !d || d.trim().length === 0)) {
+            return {
+              success: false,
+              message: "Error: all descriptions in a batch must be non-empty",
+            };
+          }
+          const added: { id: number; description: string }[] = [];
+          for (const desc of action.descriptions) {
+            const q = this.add(desc);
+            added.push({ id: q.id, description: q.description });
+          }
+
+          return { success: true, message: formatBatchAddResult(added) };
+        }
+        return {
+          success: false,
+          message: "Error: at least one description is required for add action",
+        };
+      }
+      case QUEST_ACTIONS.list: {
+        const quests = this.getAll();
+        return { success: true, message: formatQuestList(quests) };
+      }
+      case QUEST_ACTIONS.toggle: {
+        if (action.id === undefined) {
+          return { success: false, message: "Error: id is required for toggle action" };
+        }
+
+        const q = this.toggle(action.id);
+        if (!q) {
+          return { success: false, message: formatNotFound(action.id) };
+        }
+
+        return { success: true, message: formatToggleResult(action.id, q.done), quest: q };
+      }
+      case QUEST_ACTIONS.update: {
+        if (action.id === undefined) {
+          return { success: false, message: "Error: id is required for update action" };
+        }
+
+        if (!action.description) {
+          return { success: false, message: "Error: description is required for update action" };
+        }
+
+        const q = this.update(action.id, action.description);
+        if (!q) {
+          return { success: false, message: formatNotFound(action.id) };
+        }
+
+        return { success: true, message: formatUpdateResult(q), quest: q };
+      }
+      case QUEST_ACTIONS.delete: {
+        if (action.id === undefined) {
+          return { success: false, message: "Error: id is required for delete action" };
+        }
+
+        const q = this.delete(action.id);
+        if (!q) {
+          return { success: false, message: formatNotFound(action.id) };
+        }
+
+        return { success: true, message: formatDeleteResult(q), quest: q };
+      }
+      case QUEST_ACTIONS.clear: {
+        const count = this.clear(action.all);
+        const message = action.all
+          ? `Cleared ${count} quests`
+          : `Cleared ${count} completed quests`;
+
+        return { success: true, message };
+      }
+      case QUEST_ACTIONS.reorder: {
+        if (action.id === undefined)
+          return { success: false, message: "Error: id is required for reorder action" };
+
+        if (action.targetIndex === undefined)
+          return { success: false, message: "Error: targetIndex is required for reorder action" };
+
+        const q = this.reorder(action.id, action.targetIndex);
+        if (!q) return { success: false, message: formatNotFound(action.id) };
+
+        return { success: true, message: `Reordered quest #${q.id}: ${q.description}`, quest: q };
+      }
+      case QUEST_ACTIONS.revert: {
+        return this.revert();
+      }
+      default: {
+        return { success: false, message: `Unknown action: ${(action as { type: string }).type}` };
+      }
+    }
+  }
+
+  reconstructFromSession(ctx: ExtensionContext): void {
+    const branch = ctx.sessionManager.getBranch();
+    let lastState: Record<string, unknown> | undefined;
+    let toolResults = 0;
+
+    for (const entry of branch) {
+      if (
+        entry.type === "message" &&
+        "message" in entry &&
+        entry.message.role === "toolResult" &&
+        entry.message.toolName === "quest"
+      ) {
+        toolResults++;
+        lastState = entry.message.details;
+      }
+    }
+
+    if (lastState) {
+      const quests = lastState.quests;
+      const nextId = lastState.nextId;
+      const questCount = Array.isArray(quests) ? quests.length : 0;
+
+      this.quests = Array.isArray(quests) ? [...(quests as Quest[])] : [];
+      this.nextId = typeof nextId === "number" ? nextId : 1;
+      logger.debug("quests:state", "reconstruct", { toolResults, questCount, nextId: this.nextId });
+    } else {
+      this.quests = [];
+      this.nextId = 1;
+      logger.debug("quests:state", "reconstruct-empty", { toolResults });
+    }
+
+    this.history = [];
+  }
+}
+
+export function makeToolResult(
+  text: string,
+  questLog: QuestLog,
+  displayQuests?: Quest[],
+): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text }],
+    details: {
+      quests: questLog.getAll(),
+      nextId: questLog.getNextId(),
+      displayQuests,
+    },
+  };
+}

package/src/quest/formatters.ts

@@ -0,0 +1,35 @@
+export function formatQuestList(
+  quests: { id: number; description: string; done: boolean }[],
+): string {
+  if (quests.length === 0) return "No quests.";
+
+  return quests.map((q, i) => `#${i + 1} [${q.done ? "x" : " "}] ${q.description}`).join("\n");
+}
+
+export function formatAddResult(q: { id: number; description: string }): string {
+  return `Added quest #${q.id}: ${q.description}`;
+}
+
+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 formatToggleResult(id: number, done: boolean): string {
+  return `Quest #${id} ${done ? "done" : "undone"}`;
+}
+
+export function formatUpdateResult(q: { id: number; description: string }): string {
+  return `Updated quest #${q.id}: ${q.description}`;
+}
+
+export function formatDeleteResult(q: { id: number; description: string }): string {
+  return `Deleted quest #${q.id}: ${q.description}`;
+}
+
+export function formatClearResult(count: number): string {
+  return `Cleared ${count} quests`;
+}
+
+export function formatNotFound(id: number): string {
+  return `Quest #${id} not found`;
+}

package/src/quest/tracker.ts

@@ -0,0 +1,87 @@
+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.";
+
+export class QuestUsageTracker {
+  private totalToolCalls = 0;
+  private consecutiveNonQuestToolCalls = 0;
+  private hasEverUsedQuestTool = false;
+  private lastQuestToolTime = 0;
+  private nudgedThisTurn = false;
+
+  onToolExecution(toolName: string): void {
+    this.totalToolCalls++;
+    if (toolName === "quest") {
+      this.hasEverUsedQuestTool = true;
+      this.lastQuestToolTime = Date.now();
+      this.consecutiveNonQuestToolCalls = 0;
+    } else {
+      this.consecutiveNonQuestToolCalls++;
+    }
+  }
+
+  clearTurnNudge(): void {
+    this.nudgedThisTurn = false;
+  }
+
+  getNudge(activeQuestCount: number, latestPrompt?: string): string | undefined {
+    if (this.nudgedThisTurn) return undefined;
+
+    // 1. Initialization nudge
+    if (this.totalToolCalls >= 3 && !this.hasEverUsedQuestTool) {
+      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}`;
+    }
+
+    // 2. 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}`;
+    }
+
+    // 3. 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.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}`;
+    }
+
+    // 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}`;
+    }
+
+    // 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}`;
+    }
+
+    return undefined;
+  }
+
+  private isComplexPrompt(prompt: string): boolean {
+    const lower = prompt.toLowerCase();
+    return COMPLEX_TASK_KEYWORDS.some((kw) => lower.includes(kw));
+  }
+}

package/src/quest/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Core domain types and action constants for the quest system.
+ */
+
+export const QUEST_ACTIONS = {
+  add: "add",
+  list: "list",
+  toggle: "toggle",
+  update: "update",
+  delete: "delete",
+  clear: "clear",
+  reorder: "reorder",
+  revert: "revert",
+} as const;
+
+export const QUEST_ACTION_VALUES = [
+  QUEST_ACTIONS.add,
+  QUEST_ACTIONS.list,
+  QUEST_ACTIONS.toggle,
+  QUEST_ACTIONS.update,
+  QUEST_ACTIONS.delete,
+  QUEST_ACTIONS.clear,
+  QUEST_ACTIONS.reorder,
+  QUEST_ACTIONS.revert,
+] as const;
+
+export type QuestActionType = (typeof QUEST_ACTION_VALUES)[number];
+
+export interface Quest {
+  id: number;
+  description: string;
+  additionalContext?: string;
+  done: boolean;
+  createdAt: number;
+}

package/src/renderers/commands.ts

@@ -1,7 +1,7 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { logger } from "../logger.js";
-import type { Quest } from "../quests.js";
+import type { Quest } from "../quest/types.js";
 
 export class QuestListWidget {
   private cachedWidth?: number;
@@ -24,10 +24,12 @@ export class QuestListWidget {
       this.onClose();
       return;
     }
+
     if (matchesKey(data, Key.tab)) {
       this.nextPage();
       return;
     }
+
     if (matchesKey(data, Key.shift(Key.tab))) {
       this.prevPage();
       return;
@@ -45,6 +47,7 @@ export class QuestListWidget {
       to: next,
       totalPages: this.totalPages,
     });
+
     this.page = next;
     this.invalidate();
   }
@@ -56,6 +59,7 @@ export class QuestListWidget {
       to: prev,
       totalPages: this.totalPages,
     });
+
     this.page = prev;
     this.invalidate();
   }
@@ -100,24 +104,29 @@ export class QuestListWidget {
       const filled = Math.round((doneCount / total) * barWidth);
       const empty = barWidth - filled;
       const bar = th.fg("success", "█".repeat(filled)) + th.fg("dim", "░".repeat(empty));
+
       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 (const q of pageQuests) {
+      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", `#${q.id}`);
+        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));
       }
 
       if (this.totalPages > 1) {
-        lines.push("");
         const pageInfo = `  Page ${this.page + 1}/${this.totalPages}  ${th.fg("dim", "· Tab/Shift+Tab to navigate")}`;
+
+        lines.push("");
         lines.push(truncateToWidth(pageInfo, width));
       }
     }