pi-quests 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# pi-quests Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-10
+
+- feat: add session-scoped quest log with tools, commands, and TUI widgets
+  - add `QuestLog` with history stack, revert, and session reconstruction
+  - expose `quest` tool with add, list, toggle, update, delete, clear, and revert
+  - add `/quests` command namespace with interactive list widget and pagination
+  - split renderers into dedicated tools, commands, and changelog modules
+  - include `AGENTS.md` and concise docs for architecture, patterns, and reference
+- chore: setup initial pi extension boilerplate
+

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kalindu De Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# pi-quests
+
+[![version 0.1.0](https://img.shields.io/badge/version-0.1.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)
+
+A quest-log for your [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Keep your agent on track, one quest at a time.
+
+## Why pi-quests?
+
+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.
+
+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
+- **Session-scoped** — quests live with the session, vanish when you start fresh
+
+## Install
+
+TBD
+
+## Quick start
+
+**See the extension version:**
+```bash
+/quests version
+```
+
+**View the changelog:**
+```bash
+/quests changelog
+```
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [Roadmap](docs/roadmap.md) | Feature backlog and progress tracker |
+| [Changelog](CHANGELOG.md) | Version history |
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-quests",
+  "version": "0.1.0",
+  "description": "A quest-log for your pi. Keep your agent on track, one quest at a time.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "quests",
+    "snapshot",
+    "rollback",
+    "todo"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalindudc/pi-quests.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@mariozechner/pi-coding-agent": "^0.63.2",
+    "@mariozechner/pi-tui": "^0.63.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "style": "biome check ./src ./test",
+    "style:fix": "biome check --write --unsafe --no-errors-on-unmatched ./src ./test",
+    "format": "biome format --write --no-errors-on-unmatched ./src ./test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  }
+}

package/src/commands/quests.ts

@@ -0,0 +1,220 @@
+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/index.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createQuestsHandler } from "./commands/quests.js";
+import { QuestLog } from "./quests.js";
+import { questChangelogRenderer } from "./renderers/changelog.js";
+import { registerQuestTool } from "./tools/quest.js";
+
+/**
+ * pi-quests
+ *
+ * A quest-log extension for pi-coding-agent.
+ *
+ * Roadmap:
+ * - Register tools for agents to add, list, and manage quest items.
+ * - Snapshot relevant session state at each quest milestone.
+ * - Provide rollback support to restore a previous snapshot.
+ */
+export default function (pi: ExtensionAPI): void {
+  const questLog = new QuestLog();
+
+  pi.on("session_start", async (_event, ctx) => questLog.reconstructFromSession(ctx));
+  pi.on("session_tree", async (_event, ctx) => questLog.reconstructFromSession(ctx));
+
+  registerQuestTool(pi, questLog);
+
+  // Register custom message renderers
+  pi.registerMessageRenderer("quest-changelog", questChangelogRenderer);
+
+  // Register the top-level /quests command dispatcher.
+  pi.registerCommand("quests", {
+    description: "Quest commands: /quests [help] to see usage",
+    handler: createQuestsHandler(pi, questLog),
+  });
+}

package/src/logger.ts

@@ -0,0 +1,15 @@
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const LOG_FILE = "/tmp/logs/pi-quests/debug.log";
+
+mkdirSync(dirname(LOG_FILE), { recursive: true });
+
+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);
+  },
+};

package/src/quests.ts

@@ -0,0 +1,222 @@
+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`;
+}

package/src/renderers/changelog.ts

@@ -0,0 +1,26 @@
+import type { MessageRenderer, MessageRenderOptions, Theme } from "@mariozechner/pi-coding-agent";
+import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import { Markdown } from "@mariozechner/pi-tui";
+import { logger } from "../logger.js";
+
+export const questChangelogRenderer: MessageRenderer<{ content: string }> = (
+  message,
+  _options: MessageRenderOptions,
+  _theme: Theme,
+): Component | undefined => {
+  logger.debug("quest-changelog:renderer", "render-called", {
+    hasDetails: !!message.details,
+    hasContent: !!message.details?.content,
+    contentLength: message.details?.content?.length ?? 0,
+  });
+
+  const data = message.details;
+  if (!data?.content) {
+    logger.debug("quest-changelog:renderer", "no-content-returning-undefined");
+    return undefined;
+  }
+
+  logger.debug("quest-changelog:renderer", "creating-markdown");
+  return new Markdown(data.content.trim(), 1, 1, getMarkdownTheme());
+};

package/src/renderers/commands.ts

@@ -0,0 +1,141 @@
+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";
+
+export class QuestListWidget {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  private page = 0;
+  private readonly pageSize = 10;
+
+  constructor(
+    private quests: Quest[],
+    private theme: Theme,
+    private onClose: () => void,
+  ) {
+    logger.debug("quests:widget", "create", { questCount: quests.length });
+  }
+
+  handleInput(data: string): void {
+    logger.debug("quests:widget", "handleInput", { data });
+    if (matchesKey(data, Key.escape) || data === "q" || data === "Q") {
+      logger.debug("quests:widget", "close");
+      this.onClose();
+      return;
+    }
+    if (matchesKey(data, Key.tab)) {
+      this.nextPage();
+      return;
+    }
+    if (matchesKey(data, Key.shift(Key.tab))) {
+      this.prevPage();
+      return;
+    }
+  }
+
+  private get totalPages(): number {
+    return Math.max(1, Math.ceil(this.quests.length / this.pageSize));
+  }
+
+  private nextPage(): void {
+    const next = (this.page + 1) % this.totalPages;
+    logger.debug("quests:widget", "nextPage", {
+      from: this.page,
+      to: next,
+      totalPages: this.totalPages,
+    });
+    this.page = next;
+    this.invalidate();
+  }
+
+  private prevPage(): void {
+    const prev = (this.page - 1 + this.totalPages) % this.totalPages;
+    logger.debug("quests:widget", "prevPage", {
+      from: this.page,
+      to: prev,
+      totalPages: this.totalPages,
+    });
+    this.page = prev;
+    this.invalidate();
+  }
+
+  render(width: number): string[] {
+    if (this.cachedWidth === width && this.cachedLines) {
+      return this.cachedLines;
+    }
+    logger.debug("quests:widget", "render", {
+      width,
+      page: this.page,
+      totalPages: this.totalPages,
+      totalQuests: this.quests.length,
+    });
+
+    const th = this.theme;
+    const lines: string[] = [];
+    const total = this.quests.length;
+    const doneCount = this.quests.filter((q) => q.done).length;
+
+    // Top accent border
+    lines.push(th.fg("accent", "─".repeat(width)));
+
+    // Header with title and completion stats
+    const title = th.fg("accent", th.bold("  Quest Log "));
+    const stats = total > 0 ? th.fg("muted", `${doneCount}/${total} completed  `) : "";
+    const headerGap = Math.max(0, width - visibleWidth(title) - visibleWidth(stats));
+    lines.push(truncateToWidth(title + " ".repeat(headerGap) + stats, width));
+
+    lines.push("");
+
+    if (this.quests.length === 0) {
+      lines.push(
+        truncateToWidth(
+          `  ${th.fg("dim", "No active quests. Add one with /quests add <description>")}`,
+          width,
+        ),
+      );
+    } else {
+      // Mini progress bar
+      const barWidth = Math.min(width - 4, 24);
+      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) {
+        const marker = q.done ? th.fg("success", "  ✓ ") : th.fg("muted", "  ○ ");
+        const idStr = th.fg(q.done ? "dim" : "accent", `#${q.id}`);
+        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(truncateToWidth(pageInfo, width));
+      }
+    }
+
+    lines.push("");
+    lines.push(truncateToWidth(`  ${th.fg("dim", "Press q or Esc to close")}`, width));
+
+    // Bottom accent border
+    lines.push(th.fg("accent", "─".repeat(width)));
+
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    logger.debug("quests:widget", "invalidate");
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}

package/src/renderers/tools.ts

@@ -0,0 +1,69 @@
+import type { AgentToolResult, Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { logger } from "../logger.js";
+
+type QuestArgs = {
+  action: string;
+  description?: string;
+  descriptions?: string[];
+  id?: number;
+};
+
+export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown): Text {
+  logger.debug("quests:tool", "renderCall", { action: args.action, id: args.id });
+  const actionText = theme.fg("toolTitle", theme.bold("quest ")) + theme.fg("accent", args.action);
+
+  if (args.action === "add" && args.descriptions && args.descriptions.length > 0) {
+    const n = args.descriptions.length;
+    return new Text(
+      `${actionText} ${theme.fg("muted", `[${n} quest${n !== 1 ? "s" : ""}]`)}`,
+      0,
+      0,
+    );
+  }
+
+  if (args.action === "add" && args.description) {
+    const preview =
+      args.description.length > 60 ? `${args.description.slice(0, 60)}…` : args.description;
+    return new Text(`${actionText} ${theme.fg("muted", preview)}`, 0, 0);
+  }
+
+  if (
+    (args.action === "toggle" || args.action === "update" || args.action === "delete") &&
+    args.id !== undefined
+  ) {
+    return new Text(`${actionText} ${theme.fg("muted", `#${args.id}`)}`, 0, 0);
+  }
+
+  if (args.action === "revert") {
+    return new Text(actionText, 0, 0);
+  }
+
+  return new Text(actionText, 0, 0);
+}
+
+export function renderQuestResult(
+  result: AgentToolResult<unknown>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  _context: unknown,
+): Text {
+  logger.debug("quests:tool", "renderResult", {
+    expanded: options.expanded,
+    isPartial: options.isPartial,
+  });
+  const details = result.details as
+    | { quests?: Array<{ id: number; description: string; done: boolean }> }
+    | undefined;
+
+  if (details?.quests && details.quests.length > 0) {
+    const lines = details.quests.map((q) => {
+      const marker = q.done ? theme.fg("success", "✓") : theme.fg("dim", "○");
+      return `${marker} ${theme.fg("text", `#${q.id}`)} ${theme.fg("muted", q.description)}`;
+    });
+    return new Text(lines.join("\n"), 0, 0);
+  }
+
+  const text = result.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("\n");
+  return new Text(theme.fg("text", text), 0, 0);
+}

package/src/tools/quest.ts

@@ -0,0 +1,136 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import { logger } from "../logger.js";
+import {
+  formatBatchAddResult,
+  formatClearResult,
+  formatDeleteResult,
+  formatNotFound,
+  formatQuestList,
+  formatToggleResult,
+  formatUpdateResult,
+  makeToolResult,
+  type QuestLog,
+} from "../quests.js";
+import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
+
+export const QuestParams = Type.Object({
+  action: StringEnum(["add", "list", "toggle", "update", "delete", "clear", "revert"] as const),
+  description: Type.Optional(Type.String()),
+  descriptions: Type.Optional(Type.Array(Type.String())),
+  id: Type.Optional(Type.Number()),
+});
+
+export async function questToolExecute(
+  questLog: QuestLog,
+  toolCallId: string,
+  params: Static<typeof QuestParams>,
+): Promise<AgentToolResult<unknown>> {
+  logger.debug("quests:tool", "execute", { toolCallId, action: params.action, id: params.id });
+
+  switch (params.action) {
+    case "add": {
+      if (params.descriptions && params.descriptions.length > 0) {
+        logger.debug("quests:tool", "add-batch", { count: params.descriptions.length, toolCallId });
+        const added: { id: number; description: string }[] = [];
+        for (const desc of params.descriptions) {
+          const q = questLog.add(desc);
+          added.push({ id: q.id, description: q.description });
+        }
+        logger.debug("quests:tool", "add-batch-complete", { toolCallId, added: added.length });
+        return makeToolResult(formatBatchAddResult(added), questLog);
+      }
+      if (!params.description) {
+        logger.debug("quests:tool", "add-missing-description", { toolCallId });
+        return makeToolResult("Error: description is required for add action", questLog);
+      }
+      const q = questLog.add(params.description);
+      logger.debug("quests:tool", "add-complete", { toolCallId, id: q.id });
+      return makeToolResult(`Added quest #${q.id}: ${q.description}`, questLog);
+    }
+    case "list": {
+      const quests = questLog.getAll();
+      logger.debug("quests:tool", "list", { toolCallId, count: quests.length });
+      return makeToolResult(formatQuestList(quests), questLog);
+    }
+    case "toggle": {
+      if (params.id === undefined) {
+        logger.debug("quests:tool", "toggle-missing-id", { toolCallId });
+        return makeToolResult("Error: id is required for toggle action", questLog);
+      }
+      const q = questLog.toggle(params.id);
+      if (!q) {
+        logger.debug("quests:tool", "toggle-not-found", { toolCallId, id: params.id });
+        return makeToolResult(formatNotFound(params.id), questLog);
+      }
+      logger.debug("quests:tool", "toggle-complete", {
+        toolCallId,
+        id: params.id,
+        state: q.done,
+      });
+      return makeToolResult(formatToggleResult(params.id, q.done), questLog);
+    }
+    case "update": {
+      if (params.id === undefined) {
+        logger.debug("quests:tool", "update-missing-id", { toolCallId });
+        return makeToolResult("Error: id is required for update action", questLog);
+      }
+      if (!params.description) {
+        logger.debug("quests:tool", "update-missing-description", { toolCallId, id: params.id });
+        return makeToolResult("Error: description is required for update action", questLog);
+      }
+      const q = questLog.update(params.id, params.description);
+      if (!q) {
+        logger.debug("quests:tool", "update-not-found", { toolCallId, id: params.id });
+        return makeToolResult(formatNotFound(params.id), questLog);
+      }
+      logger.debug("quests:tool", "update-complete", { toolCallId, id: params.id });
+      return makeToolResult(formatUpdateResult(q), questLog);
+    }
+    case "delete": {
+      if (params.id === undefined) {
+        logger.debug("quests:tool", "delete-missing-id", { toolCallId });
+        return makeToolResult("Error: id is required for delete action", questLog);
+      }
+      const q = questLog.delete(params.id);
+      if (!q) {
+        logger.debug("quests:tool", "delete-not-found", { toolCallId, id: params.id });
+        return makeToolResult(formatNotFound(params.id), questLog);
+      }
+      logger.debug("quests:tool", "delete-complete", { toolCallId, id: params.id });
+      return makeToolResult(formatDeleteResult(q), questLog);
+    }
+    case "clear": {
+      const count = questLog.clear();
+      logger.debug("quests:tool", "clear-complete", { toolCallId, count });
+      return makeToolResult(formatClearResult(count), questLog);
+    }
+    case "revert": {
+      const result = questLog.revert();
+      logger.debug("quests:tool", "revert-complete", { toolCallId, success: result.success });
+      return makeToolResult(result.message, questLog);
+    }
+    default: {
+      logger.debug("quests:tool", "unknown-action", {
+        toolCallId,
+        action: (params as { action: string }).action,
+      });
+      return makeToolResult(`Unknown action: ${(params as { action: string }).action}`, questLog);
+    }
+  }
+}
+
+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",
+    parameters: QuestParams,
+    execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
+      questToolExecute(questLog, toolCallId, params),
+    renderCall: renderQuestCall,
+    renderResult: renderQuestResult,
+  });
+}

package/src/version.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+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"));
+
+export const VERSION: string = packageJson.version;
+export const CHANGELOG_PATH: string = resolve(__dirname, "../CHANGELOG.md");