pi-quests 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [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.2.0](https://img.shields.io/badge/version-0.2.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.2.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,134 @@
+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.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]: () => ({ type: QUEST_ACTIONS.clear }),
+  [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.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("  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/commands/parse-args.ts

@@ -0,0 +1,78 @@
+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 }
+  | { 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 { action: QUEST_ACTIONS.clear };
+  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);
+
+  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 };
+}

package/src/index.ts

@@ -1,8 +1,9 @@
 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 { 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 +17,54 @@ 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);
+    if (!nudge) return undefined;
+
+    const reminder: import("@mariozechner/pi-ai").UserMessage = {
+      role: "user",
+      content: nudge,
+      timestamp: Date.now(),
+    };
+    return { messages: [...event.messages, reminder] };
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    const quests = questLog.getAll();
+    const gate =
+      "# Quest Management\nBefore 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.\n\n";
+
+    let reminder =
+      "## Quest Management\nUse the quest tool VERY frequently to track tasks, plans, and progress throughout the conversation. It is critical that you toggle quests to done as soon as you complete them. NEVER batch up multiple tasks before marking them completed.\n\nNEVER create a single vague quest for broad requests. Analyze the user's intent and break it into specific, independent, actionable quests that each represent a concrete step.";
+    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: `${gate}${event.systemPrompt}\n\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);
   },
 };