pi-quests 0.1.0 → 0.2.0

package/src/tools/handler.ts

@@ -0,0 +1,100 @@
+import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Static } from "@sinclair/typebox";
+import { logger } from "../logger.js";
+import { makeToolResult, type QuestAction, type QuestLog } from "../quest/dataplane.js";
+import { QUEST_ACTIONS } from "../quest/types.js";
+import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
+import { QuestParams } from "./params.js";
+
+type QuestToolParams = Static<typeof QuestParams>;
+
+const toolHandlers: {
+  [K in QuestToolParams["action"]]: (
+    questLog: QuestLog,
+    params: QuestToolParams,
+    toolCallId: string,
+  ) => AgentToolResult<unknown>;
+} = {
+  [QUEST_ACTIONS.add](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.add,
+      descriptions: params.descriptions,
+    });
+  },
+  [QUEST_ACTIONS.list](questLog, _params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.list });
+  },
+  [QUEST_ACTIONS.toggle](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.toggle, id: params.id });
+  },
+  [QUEST_ACTIONS.update](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.update,
+      id: params.id,
+      description: params.description,
+    });
+  },
+  [QUEST_ACTIONS.delete](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.delete, id: params.id });
+  },
+  [QUEST_ACTIONS.clear](questLog, _params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.clear });
+  },
+  [QUEST_ACTIONS.revert](questLog, _params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.revert });
+  },
+};
+
+function runTool(
+  questLog: QuestLog,
+  toolCallId: string,
+  action: QuestAction,
+): AgentToolResult<unknown> {
+  const result = questLog.execute(action);
+  logger.debug("quests:tool", "execute-complete", { toolCallId, success: result.success });
+
+  const displayQuests =
+    action.type === QUEST_ACTIONS.add ||
+    action.type === QUEST_ACTIONS.list ||
+    action.type === QUEST_ACTIONS.revert
+      ? questLog.getAll()
+      : result.quest
+        ? [result.quest]
+        : undefined;
+
+  return makeToolResult(result.message, questLog, displayQuests);
+}
+
+export async function questToolExecute(
+  questLog: QuestLog,
+  toolCallId: string,
+  params: QuestToolParams,
+): Promise<AgentToolResult<unknown>> {
+  logger.debug("quests:tool", "execute", { toolCallId, action: params.action, id: params.id });
+  const handler = toolHandlers[params.action];
+  return handler(questLog, params, toolCallId);
+}
+
+export function registerQuestTool(pi: ExtensionAPI, questLog: QuestLog): void {
+  logger.debug("quests:tool", "register");
+  pi.registerTool({
+    name: "quest",
+    label: "Quest",
+    description:
+      "Manage the session quest log. Use this VERY frequently to track tasks, plans, and progress throughout the conversation.",
+    promptSnippet: "Add, list, toggle, update, delete, clear, or revert quest items",
+    promptGuidelines: [
+      "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.",
+      "It is critical that you toggle quests to done as soon as you complete them. Do NOT batch completions.",
+      "Before delegating to a minion, add a quest for the delegated task.",
+      "If you are unsure what to do next, use the list action to check active quests.",
+    ],
+    parameters: QuestParams,
+    execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
+      questToolExecute(questLog, toolCallId, params),
+    renderCall: renderQuestCall,
+    renderResult: renderQuestResult,
+  });
+}

package/src/tools/params.ts

@@ -0,0 +1,24 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { QUEST_ACTION_VALUES } from "../quest/types.js";
+
+export const QuestParams = Type.Object({
+  action: StringEnum(QUEST_ACTION_VALUES, {
+    description: "The quest action to perform",
+  }),
+  descriptions: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Array of quest descriptions (required for add action)",
+    }),
+  ),
+  description: Type.Optional(
+    Type.String({
+      description: "New description (required for update action)",
+    }),
+  ),
+  id: Type.Optional(
+    Type.Number({
+      description: "Quest ID (required for toggle, update, delete actions)",
+    }),
+  ),
+});

package/src/version.ts

@@ -5,7 +5,14 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const packageJsonPath = resolve(__dirname, "../package.json");
-const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+let cachedVersion: string | undefined;
+
+export function getVersion(): string {
+  if (cachedVersion === undefined) {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    cachedVersion = packageJson.version as string;
+  }
+  return cachedVersion;
+}
 
-export const VERSION: string = packageJson.version;
 export const CHANGELOG_PATH: string = resolve(__dirname, "../CHANGELOG.md");

package/src/commands/quests.ts

@@ -1,220 +0,0 @@
-import { readFileSync } from "node:fs";
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { logger } from "../logger.js";
-import {
-  formatClearResult,
-  formatDeleteResult,
-  formatNotFound,
-  formatToggleResult,
-  formatUpdateResult,
-  type QuestLog,
-} from "../quests.js";
-import { QuestListWidget } from "../renderers/commands.js";
-import { CHANGELOG_PATH, VERSION } from "../version.js";
-
-// Helper function to reverse changelog sections so newest appears first
-function reverseChangelog(content: string): string {
-  const lines = content.split("\n");
-  const sections: string[][] = [];
-  let currentSection: string[] = [];
-
-  for (const line of lines) {
-    if (line.startsWith("## [")) {
-      if (currentSection.length > 0) {
-        sections.push(currentSection);
-      }
-      currentSection = [line];
-    } else {
-      currentSection.push(line);
-    }
-  }
-
-  if (currentSection.length > 0) {
-    sections.push(currentSection);
-  }
-
-  // Reverse sections and flatten
-  const reversed = sections.reverse().flat();
-  return reversed.join("\n");
-}
-
-export type ParsedArgs =
-  | { action: "add"; description: string }
-  | { action: "list" }
-  | { action: "toggle"; id: number }
-  | { action: "update"; id: number; description: string }
-  | { action: "delete"; id: number }
-  | { action: "clear" }
-  | { action: "revert" }
-  | { action: "help" }
-  | { action: "version" }
-  | { action: "changelog" }
-  | { error: string };
-
-export function parseQuestArgs(args: string): ParsedArgs {
-  logger.debug("quests:cmd", "parse-args", { args });
-  const tokens = args.trim().split(/\s+/).filter(Boolean);
-  if (tokens.length === 0) {
-    logger.debug("quests:cmd", "parse-args-empty", { action: "list" });
-    return { action: "list" };
-  }
-  const action = tokens[0];
-  if (action === "version") return { action: "version" };
-  if (action === "changelog") return { action: "changelog" };
-  if (action === "help" || action === "h") return { action: "help" };
-  if (action === "list") return { action: "list" };
-  if (action === "clear") return { action: "clear" };
-  if (action === "revert") return { action: "revert" };
-  if (action === "add") {
-    const description = tokens.slice(1).join(" ").trim();
-    if (!description) return { error: "Usage: /quests add <description>" };
-    return { action: "add", description };
-  }
-  if (action === "toggle") {
-    const idStr = tokens[1];
-    const id = idStr ? Number(idStr) : NaN;
-    if (Number.isNaN(id)) return { error: "Usage: /quests toggle <id>" };
-    return { action: "toggle", id };
-  }
-  if (action === "delete") {
-    const idStr = tokens[1];
-    const id = idStr ? Number(idStr) : NaN;
-    if (Number.isNaN(id)) return { error: "Usage: /quests delete <id>" };
-    return { action: "delete", id };
-  }
-  if (action === "update") {
-    const idStr = tokens[1];
-    const id = idStr ? Number(idStr) : NaN;
-    if (Number.isNaN(id)) return { error: "Usage: /quests update <id> <description>" };
-    const description = tokens.slice(2).join(" ").trim();
-    if (!description) return { error: "Usage: /quests update <id> <description>" };
-    return { action: "update", id, description };
-  }
-  return { error: `Unknown subcommand: ${action}. Use /quests help to see available commands.` };
-}
-
-export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog) {
-  return async function handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
-    logger.debug("quests:cmd", "handler", { args, hasUI: ctx.hasUI });
-    const parsed = parseQuestArgs(args);
-    if ("error" in parsed) {
-      logger.debug("quests:cmd", "handler-error", { error: parsed.error });
-      ctx.ui.notify(parsed.error, "error");
-      return;
-    }
-
-    switch (parsed.action) {
-      case "version": {
-        logger.debug("quests:cmd", "version", { version: VERSION });
-        ctx.ui.notify(`pi-quests v${VERSION}`, "info");
-        return;
-      }
-      case "changelog": {
-        logger.debug("quests:cmd", "changelog", { changelogPath: CHANGELOG_PATH });
-
-        try {
-          const content = readFileSync(CHANGELOG_PATH, "utf-8");
-          logger.debug("quests:cmd", "changelog-read", { contentLength: content.length });
-          const reversedContent = reverseChangelog(content);
-          logger.debug("quests:cmd", "changelog-reversed");
-
-          pi.sendMessage({
-            customType: "quest-changelog",
-            content: "",
-            display: true,
-            details: { content: reversedContent },
-          });
-
-          logger.debug("quests:cmd", "changelog-sent");
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          logger.debug("quests:cmd", "changelog-error", { error: errorMessage });
-          ctx.ui.notify(`Failed to read changelog: ${errorMessage}`, "error");
-        }
-        return;
-      }
-      case "add": {
-        const q = questLog.add(parsed.description);
-        logger.debug("quests:cmd", "add", { id: q.id });
-        ctx.ui.notify(`Added quest #${q.id}`, "info");
-        return;
-      }
-      case "list": {
-        if (!ctx.hasUI) {
-          logger.debug("quests:cmd", "list-no-ui");
-          ctx.ui.notify("Interactive mode required", "error");
-          return;
-        }
-        logger.debug("quests:cmd", "list-open-widget", { count: questLog.getAll().length });
-        await ctx.ui.custom(
-          (_, theme, __, done) =>
-            new QuestListWidget(questLog.getAll(), theme, () => done(undefined)),
-        );
-        logger.debug("quests:cmd", "list-widget-closed");
-        return;
-      }
-      case "toggle": {
-        const q = questLog.toggle(parsed.id);
-        if (!q) {
-          logger.debug("quests:cmd", "toggle-not-found", { id: parsed.id });
-          ctx.ui.notify(formatNotFound(parsed.id), "error");
-          return;
-        }
-        logger.debug("quests:cmd", "toggle", { id: parsed.id, state: q.done });
-        ctx.ui.notify(formatToggleResult(parsed.id, q.done), "info");
-        return;
-      }
-      case "update": {
-        const q = questLog.update(parsed.id, parsed.description);
-        if (!q) {
-          logger.debug("quests:cmd", "update-not-found", { id: parsed.id });
-          ctx.ui.notify(formatNotFound(parsed.id), "error");
-          return;
-        }
-        logger.debug("quests:cmd", "update", { id: parsed.id });
-        ctx.ui.notify(formatUpdateResult(q), "info");
-        return;
-      }
-      case "delete": {
-        const q = questLog.delete(parsed.id);
-        if (!q) {
-          logger.debug("quests:cmd", "delete-not-found", { id: parsed.id });
-          ctx.ui.notify(formatNotFound(parsed.id), "error");
-          return;
-        }
-        logger.debug("quests:cmd", "delete", { id: parsed.id });
-        ctx.ui.notify(formatDeleteResult(q), "info");
-        return;
-      }
-      case "clear": {
-        const count = questLog.clear();
-        logger.debug("quests:cmd", "clear", { count });
-        ctx.ui.notify(formatClearResult(count), "info");
-        return;
-      }
-      case "revert": {
-        const result = questLog.revert();
-        logger.debug("quests:cmd", "revert", { success: result.success });
-        ctx.ui.notify(result.message, result.success ? "info" : "error");
-        return;
-      }
-      case "help": {
-        logger.debug("quests:cmd", "help");
-        const lines = ["Available /quests subcommands:"];
-        lines.push("  add <description>  - Add a new quest");
-        lines.push("  list               - List all quests");
-        lines.push("  toggle <id>        - Toggle quest completion");
-        lines.push("  delete <id>        - Delete a quest");
-        lines.push("  update <id> <desc> - Update a quest description");
-        lines.push("  revert             - Revert the last quest change");
-        lines.push("  clear              - Clear all quests");
-        lines.push("  version            - Show version");
-        lines.push("  changelog          - Show changelog");
-        lines.push("  h, help            - Show this help message");
-        ctx.ui.notify(lines.join("\n"), "info");
-        logger.debug("quests:cmd", "help-complete");
-        return;
-      }
-    }
-  };
-}

package/src/quests.ts

@@ -1,222 +0,0 @@
-import type { AgentToolResult, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { logger } from "./logger.js";
-
-export interface Quest {
-  id: number;
-  description: string;
-  additionalContext?: string;
-  done: boolean;
-  createdAt: number;
-}
-
-type HistoryEntry =
-  | { type: "add"; id: number }
-  | { type: "toggle"; id: number }
-  | { type: "update"; id: number; previousDescription: string }
-  | { type: "delete"; quest: Quest; index: number }
-  | { type: "clear"; quests: Quest[]; nextId: number };
-
-export class QuestLog {
-  private quests: Quest[] = [];
-  private nextId = 1;
-  private history: HistoryEntry[] = [];
-
-  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: "add", id: quest.id });
-    logger.debug("quests:state", "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: "toggle", id });
-    logger.debug("quests:state", "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: "update", id, previousDescription: quest.description });
-    quest.description = description;
-    logger.debug("quests:state", "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: "delete", quest, index });
-    logger.debug("quests:state", "delete", { id, index, total: this.quests.length });
-    return quest;
-  }
-
-  clear(): number {
-    const count = this.quests.length;
-    this.history.push({ type: "clear", quests: [...this.quests], nextId: this.nextId });
-    this.quests = [];
-    this.nextId = 1;
-    logger.debug("quests:state", "clear", { count });
-    return count;
-  }
-
-  revert(): { success: boolean; message: string } {
-    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 });
-
-    if (entry.type === "add") {
-      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}` };
-    }
-
-    if (entry.type === "toggle") {
-      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` };
-    }
-
-    if (entry.type === "update") {
-      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` };
-    }
-
-    if (entry.type === "delete") {
-      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}` };
-    }
-
-    if (entry.type === "clear") {
-      this.quests = [...entry.quests];
-      this.nextId = entry.nextId;
-      logger.debug("quests:state", "revert-clear", { count: entry.quests.length });
-      return { success: true, message: `Reverted clear (${entry.quests.length} quests restored)` };
-    }
-
-    logger.debug("quests:state", "revert-unknown", { type: (entry as { type: string }).type });
-    return { success: false, message: "Unknown history entry" };
-  }
-
-  reconstructFromSession(ctx: ExtensionContext): void {
-    const branch = ctx.sessionManager.getBranch();
-    let lastState: { quests?: Quest[]; nextId?: number } | 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 as { quests?: Quest[]; nextId?: number } | undefined;
-      }
-    }
-
-    if (lastState) {
-      const questCount = Array.isArray(lastState.quests) ? lastState.quests.length : 0;
-      this.quests = Array.isArray(lastState.quests) ? [...lastState.quests] : [];
-      this.nextId = typeof lastState.nextId === "number" ? lastState.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): AgentToolResult<unknown> {
-  return {
-    content: [{ type: "text", text }],
-    details: { quests: questLog.getAll(), nextId: questLog.getNextId() },
-  };
-}
-
-export function formatQuestList(
-  quests: { id: number; description: string; done: boolean }[],
-): string {
-  if (quests.length === 0) return "No quests.";
-  return quests.map((q) => `#${q.id} [${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`;
-}