pi-quests 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-11
+
+- feat: add reorder action to move quests by position (dataplane, tool, /quests command, renderer, revert support)
+- feat: extend clear action with optional all flag to remove all quests regardless of done state
+- feat: detect appended completion markers (e.g. "- DONE") and inject correction nudge via context hook
+- feat: update list rendering to show 1-based positions instead of raw IDs
+- fix: inline type imports across test files to comply with no-inline-imports rule
+- chore: extract shared prompt strings into prompts.ts to eliminate duplication
+- chore: fix release workflow output mapping in create-release job
+
+## [0.2.0] - 2026-04-11
+
+- feat: add dynamic quest usage nudges via context hook
+- feat: inject quest management reminders into system prompt
+- feat: render targeted quest results and add parameter descriptions
+- chore: add npm release flow
+- chore: refactor codebase for improved maintainability
+
 ## [0.1.0] - 2026-04-10
 
 - feat: add session-scoped quest log with tools, commands, and TUI widgets

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.1.0](https://img.shields.io/badge/version-0.1.0-blue)](CHANGELOG.md)
+[![version 0.3.0](https://img.shields.io/badge/version-0.3.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)
 
@@ -10,34 +10,51 @@ A quest-log for your [pi](https://github.com/badlogic/pi-mono/tree/main/packages
 
 Long agent sessions drift. Goals get lost in tool calls, side quests multiply, and the original task is forgotten under a pile of yak hair.
 
+![Quests log in action](docs/assets/quests_log.png)
+
 pi-quests gives your agent a persistent quest log — a living TODO list for the current session. Each quest is a checkpoint the agent can create, complete, and optionally roll back to if things go sideways.
 
 - **Stay focused** — the quest log keeps the original goal visible no matter how deep the rabbit hole goes
-- **Checkpoint progress** — mark milestones as quests and capture lightweight session snapshots
-- **Rollback safety** — revert to a previous quest snapshot when exploration goes off track
+- **Checkpoint progress** — mark milestones as quests and capture lightweight session snapshots (WIP)
+- **Rollback safety** — revert to a previous quest snapshot when exploration goes off track (WIP)
 - **Session-scoped** — quests live with the session, vanish when you start fresh
 
 ## Install
 
-TBD
+```bash
+pi install npm:pi-quests
+```
 
 ## Quick start
 
-**See the extension version:**
-```bash
-/quests version
 ```
-
-**View the changelog:**
-```bash
-/quests changelog
+/quests help
+
+Available /quests subcommands:
+  add <description>  - Add a new quest
+  list               - List all quests
+  toggle <id>        - Toggle quest completion
+  delete <id>        - Delete a quest
+  update <id> <desc> - Update a quest description
+  revert             - Revert the last quest change
+  clear              - Clear all quests
+  version            - Show version
+  changelog          - Show changelog
+  h, help            - Show this help message
 ```
 
+![Quests toggle](docs/assets/quests_toggle.png)
+![Quests view](docs/assets/quests_view.png)
+
+
 ## Documentation
 
 | Doc | Description |
 |-----|-------------|
-| [Roadmap](docs/roadmap.md) | Feature backlog and progress tracker |
+| [Pattern](docs/pattern.md) | "How do I...?" recipes for common workflows |
+| [Quests](docs/quests.md) | What are quests? |
+| [Reference](docs/reference.md) | Complete tool and command schemas, types |
+| [Architecture](docs/architecture.md) | Module map, data flow diagrams, design decisions |
 | [Changelog](CHANGELOG.md) | Version history |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quests",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A quest-log for your pi. Keep your agent on track, one quest at a time.",
   "type": "module",
   "keywords": [

package/src/commands/changelog.ts

@@ -0,0 +1,9 @@
+/**
+ * Reverse changelog sections so the newest release appears first.
+ */
+export function reverseChangelog(content: string): string {
+  const parts = content.split(/^## \[/m);
+  const preamble = parts[0];
+  const sections = parts.slice(1).map((s) => `## [${s}`);
+  return [preamble, ...sections.reverse()].join("");
+}

package/src/commands/handler.ts

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+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 { CHANGELOG_PATH, getVersion } from "../version.js";
+import { reverseChangelog } from "./changelog.js";
+import { type ParsedArgs, parseQuestArgs } from "./parse-args.js";
+
+type MutatingCommand = Extract<
+  ParsedArgs,
+  {
+    action:
+      | typeof QUEST_ACTIONS.add
+      | typeof QUEST_ACTIONS.toggle
+      | typeof QUEST_ACTIONS.update
+      | typeof QUEST_ACTIONS.delete
+      | typeof QUEST_ACTIONS.clear
+      | typeof QUEST_ACTIONS.reorder
+      | typeof QUEST_ACTIONS.revert;
+  }
+>["action"];
+
+const commandActionBuilders: {
+  [K in MutatingCommand]: (parsed: Extract<ParsedArgs, { action: K }>) => QuestAction;
+} = {
+  [QUEST_ACTIONS.add]: (p) => ({ type: QUEST_ACTIONS.add, descriptions: p.descriptions }),
+  [QUEST_ACTIONS.toggle]: (p) => ({ type: QUEST_ACTIONS.toggle, id: p.id }),
+  [QUEST_ACTIONS.update]: (p) => ({
+    type: QUEST_ACTIONS.update,
+    id: p.id,
+    description: p.description,
+  }),
+  [QUEST_ACTIONS.delete]: (p) => ({ type: QUEST_ACTIONS.delete, id: p.id }),
+  [QUEST_ACTIONS.clear]: (p) => ({ type: QUEST_ACTIONS.clear, all: p.all }),
+  [QUEST_ACTIONS.reorder]: (p) => ({
+    type: QUEST_ACTIONS.reorder,
+    id: p.id,
+    targetIndex: p.targetIndex,
+  }),
+  [QUEST_ACTIONS.revert]: () => ({ type: QUEST_ACTIONS.revert }),
+};
+
+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": {
+        const version = getVersion();
+        logger.debug("quests:cmd", "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 QUEST_ACTIONS.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 QUEST_ACTIONS.add:
+      case QUEST_ACTIONS.toggle:
+      case QUEST_ACTIONS.update:
+      case QUEST_ACTIONS.delete:
+      case QUEST_ACTIONS.clear:
+      case QUEST_ACTIONS.reorder:
+      case QUEST_ACTIONS.revert: {
+        const builder = commandActionBuilders[parsed.action];
+        const action = builder(parsed as never);
+        const result = questLog.execute(action);
+
+        logger.debug("quests:cmd", parsed.action, { 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("  reorder <id> <idx> - Reorder a quest to index");
+        lines.push("  revert             - Revert the last quest change");
+        lines.push("  clear [all]        - Clear completed quests, or optionally 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/commands/parse-args.ts

@@ -0,0 +1,94 @@
+import { logger } from "../logger.js";
+import { QUEST_ACTIONS } from "../quest/types.js";
+
+export type ParsedArgs =
+  | { action: typeof QUEST_ACTIONS.add; descriptions: string[] }
+  | { action: typeof QUEST_ACTIONS.list }
+  | { action: typeof QUEST_ACTIONS.toggle; id: number }
+  | { action: typeof QUEST_ACTIONS.update; id: number; description: string }
+  | { action: typeof QUEST_ACTIONS.delete; id: number }
+  | { action: typeof QUEST_ACTIONS.clear; all?: boolean }
+  | { action: typeof QUEST_ACTIONS.reorder; id: number; targetIndex: number }
+  | { action: typeof QUEST_ACTIONS.revert }
+  | { action: "help" }
+  | { action: "version" }
+  | { action: "changelog" }
+  | { error: string };
+
+/**
+ * Parse user input from the /quests command into structured arguments.
+ */
+export function parseQuestArgs(args: string): ParsedArgs {
+  logger.debug("quests:cmd", "parse-args", { args });
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+
+  // Empty input defaults to listing quests.
+  if (tokens.length === 0) {
+    logger.debug("quests:cmd", "parse-args-empty", { action: QUEST_ACTIONS.list });
+    return { action: QUEST_ACTIONS.list };
+  }
+
+  const [command, ...rest] = tokens;
+
+  // Meta commands
+  if (command === "version") return { action: "version" };
+  if (command === "changelog") return { action: "changelog" };
+  if (command === "help" || command === "h") return { action: "help" };
+
+  // Quest actions without arguments
+  if (command === QUEST_ACTIONS.list) return { action: QUEST_ACTIONS.list };
+  if (command === QUEST_ACTIONS.clear) return parseClearArgs(rest);
+  if (command === QUEST_ACTIONS.revert) return { action: QUEST_ACTIONS.revert };
+
+  // Quest actions with arguments
+  if (command === QUEST_ACTIONS.add) return parseAddArgs(rest);
+  if (command === QUEST_ACTIONS.toggle) return parseIdAction(QUEST_ACTIONS.toggle, rest);
+  if (command === QUEST_ACTIONS.delete) return parseIdAction(QUEST_ACTIONS.delete, rest);
+  if (command === QUEST_ACTIONS.update) return parseUpdateArgs(rest);
+  if (command === QUEST_ACTIONS.reorder) return parseReorderArgs(rest);
+
+  return { error: `Unknown subcommand: ${command}. Use /quests help to see available commands.` };
+}
+
+function parseAddArgs(tokens: string[]): ParsedArgs {
+  const description = tokens.join(" ").trim();
+  if (!description) return { error: "Usage: /quests add <description>" };
+
+  return { action: QUEST_ACTIONS.add, descriptions: [description] };
+}
+
+function parseIdAction(
+  action: typeof QUEST_ACTIONS.toggle | typeof QUEST_ACTIONS.delete,
+  tokens: string[],
+): ParsedArgs {
+  const idStr = tokens[0];
+  const id = idStr ? Number(idStr) : NaN;
+  if (Number.isNaN(id)) return { error: `Usage: /quests ${action} <id>` };
+
+  return { action, id };
+}
+
+function parseUpdateArgs(tokens: string[]): ParsedArgs {
+  const idStr = tokens[0];
+  const id = idStr ? Number(idStr) : NaN;
+  if (Number.isNaN(id)) return { error: "Usage: /quests update <id> <description>" };
+
+  const description = tokens.slice(1).join(" ").trim();
+  if (!description) return { error: "Usage: /quests update <id> <description>" };
+
+  return { action: QUEST_ACTIONS.update, id, description };
+}
+
+function parseClearArgs(tokens: string[]): ParsedArgs {
+  const all = tokens[0] === "all";
+  if (tokens.length > 0 && !all) return { error: "Usage: /quests clear [all]" };
+  return { action: QUEST_ACTIONS.clear, all };
+}
+
+function parseReorderArgs(tokens: string[]): ParsedArgs {
+  const id = Number(tokens[0]);
+  const targetIndex = Number(tokens[1]);
+  if (Number.isNaN(id) || Number.isNaN(targetIndex))
+    return { error: "Usage: /quests reorder <id> <index>" };
+  return { action: QUEST_ACTIONS.reorder, id, targetIndex };
+}

package/src/index.ts

@@ -1,8 +1,11 @@
+import type { UserMessage } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { createQuestsHandler } from "./commands/quests.js";
-import { QuestLog } from "./quests.js";
+import { createQuestsHandler } from "./commands/handler.js";
+import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "./prompts.js";
+import { QuestLog } from "./quest/dataplane.js";
+import { QuestUsageTracker } from "./quest/tracker.js";
 import { questChangelogRenderer } from "./renderers/changelog.js";
-import { registerQuestTool } from "./tools/quest.js";
+import { registerQuestTool } from "./tools/handler.js";
 
 /**
  * pi-quests
@@ -16,10 +19,61 @@ import { registerQuestTool } from "./tools/quest.js";
  */
 export default function (pi: ExtensionAPI): void {
   const questLog = new QuestLog();
+  const tracker = new QuestUsageTracker();
 
   pi.on("session_start", async (_event, ctx) => questLog.reconstructFromSession(ctx));
   pi.on("session_tree", async (_event, ctx) => questLog.reconstructFromSession(ctx));
 
+  pi.on("turn_start", async () => tracker.clearTurnNudge());
+
+  pi.on("tool_execution_end", async (event) => {
+    tracker.onToolExecution(event.toolName);
+  });
+
+  pi.on("context", async (event) => {
+    const latestPrompt = event.messages
+      .filter((m) => m.role === "user")
+      .map((m) => (typeof m.content === "string" ? m.content : ""))
+      .join("\n");
+
+    const activeQuestCount = questLog.getAll().filter((q) => !q.done).length;
+    const nudge = tracker.getNudge(activeQuestCount, latestPrompt);
+
+    const fakeDoneRegex =
+      /\s[-–—]\s*(DONE|COMPLETED|FINISHED)$|\s[([](DONE|COMPLETED|FINISHED)[)\]]$/i;
+    const fakeDone = questLog.getAll().find((q) => !q.done && fakeDoneRegex.test(q.description));
+    if (!nudge && !fakeDone) return undefined;
+
+    let content = nudge ?? "";
+    if (fakeDone) {
+      content += `\nQUEST REMINDER: Quest #${fakeDone.id} has a completion marker appended to its description but is not toggled done. Use the toggle action to mark it done. NEVER append completion markers to descriptions via the update action.`;
+    }
+
+    const reminder: UserMessage = {
+      role: "user",
+      content: content.trim(),
+      timestamp: Date.now(),
+    };
+    return { messages: [...event.messages, reminder] };
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    const quests = questLog.getAll();
+    let reminder = QUEST_PROMPT_REMINDER.join("\n");
+    if (quests.length > 0) {
+      const remaining = quests.filter((q) => !q.done).length;
+      const list = quests
+        .map((q) => `#${q.id} [${q.done ? "x" : " "}] ${q.description}`)
+        .join("\n");
+
+      reminder += `\n\nActive quests (${remaining}/${quests.length}):\n${list}`;
+    }
+
+    return {
+      systemPrompt: `# Quest Management\n${QUEST_PROMPT_GATE}${event.systemPrompt}\n\n## Quest Management\n${reminder}`,
+    };
+  });
+
   registerQuestTool(pi, questLog);
 
   // Register custom message renderers

package/src/logger.ts

@@ -3,13 +3,22 @@ import { dirname } from "node:path";
 
 export const LOG_FILE = "/tmp/logs/pi-quests/debug.log";
 
-mkdirSync(dirname(LOG_FILE), { recursive: true });
+let stream: ReturnType<typeof createWriteStream> | undefined;
+
+function getStream() {
+  if (!stream) {
+    mkdirSync(dirname(LOG_FILE), { recursive: true });
+    stream = createWriteStream(LOG_FILE, { flags: "a" });
+    stream.on("error", () => {});
+  }
+  return stream;
+}
 
 export const logger = {
   debug: (namespace: string, event: string, meta?: Record<string, unknown>) => {
     const timestamp = new Date().toISOString();
     const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
     const line = `[${timestamp}] [${namespace}] ${event}${metaStr}\n`;
-    createWriteStream(LOG_FILE, { flags: "a" }).write(line);
+    getStream().write(line);
   },
 };

package/src/prompts.ts

@@ -0,0 +1,16 @@
+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.",
+  "As work evolves, use the reorder action to reflect changes in priority or sequencing.",
+  "Before delegating to a minion, add a quest for the delegated task.",
+  "For reorder, targetIndex is 0-based (array index), not a 1-based position. If the user says 'move quest to position 5', use targetIndex 4.",
+  "If you are unsure what to do next, use the list action to check active quests.",
+] 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.";