pi-quests 0.6.1 → 0.7.0

package/src/quest/formatters.ts

@@ -44,6 +44,12 @@ export function formatToggleResult(id: string, done: boolean): string {
   return `Quest [${id}] ${done ? "done" : "undone"}`;
 }
 
+export function formatBatchToggleResult(toggled: { id: string; done: boolean }[]): string {
+  return `Toggled ${toggled.length} tasks:\n${toggled
+    .map((quest) => `[${quest.id}] ${quest.done ? "done" : "undone"}`)
+    .join("\n")}`;
+}
+
 export function formatUpdateResult(q: { id: string; description: string }): string {
   return `Updated quest [${q.id}]: ${q.description}`;
 }
@@ -52,6 +58,10 @@ export function formatDeleteResult(q: { id: string; description: string }): stri
   return `Deleted quest [${q.id}]: ${q.description}`;
 }
 
+export function formatBatchDeleteResult(deleted: { id: string; description: string }[]): string {
+  return `Deleted ${deleted.length} tasks:\n${deleted.map((quest) => `[${quest.id}] ${quest.description}`).join("\n")}`;
+}
+
 export function formatNotFound(id: string): string {
   return `Quest [${id}] not found. IDs are random hex strings shown in brackets. Use the list action to see valid IDs.`;
 }
@@ -100,8 +110,12 @@ export function formatUnknownActionError(action: string): string {
   return `Unknown action: ${action}. Use the list action or check the tool schema for supported actions.`;
 }
 
-export function formatNothingToRevertError(): string {
-  return `Nothing to revert. The history is empty because no mutating actions have been performed yet.`;
+export function formatNothingToUndoError(): string {
+  return `Nothing to undo. The history is empty because no mutating actions have been performed yet.`;
+}
+
+export function formatNothingToRedoError(): string {
+  return `Nothing to redo. The redo stack is empty because no actions have been undone yet.`;
 }
 
 export function formatReorderedQuestNotFoundError(): string {

package/src/quest/types.ts

@@ -10,7 +10,8 @@ export const QUEST_ACTIONS = {
   delete: "delete",
   clear: "clear",
   reorder: "reorder",
-  revert: "revert",
+  undo: "undo",
+  redo: "redo",
   reparent: "reparent",
   rules: "rules",
   skill: "skill",
@@ -26,7 +27,8 @@ export const QUEST_ACTION_VALUES = [
   QUEST_ACTIONS.delete,
   QUEST_ACTIONS.clear,
   QUEST_ACTIONS.reorder,
-  QUEST_ACTIONS.revert,
+  QUEST_ACTIONS.undo,
+  QUEST_ACTIONS.redo,
   QUEST_ACTIONS.reparent,
   QUEST_ACTIONS.rules,
   QUEST_ACTIONS.skill,

package/src/renderers/tools.ts

@@ -11,6 +11,7 @@ type QuestArgs = {
   descriptions?: string[];
   targetId?: string;
   id?: string;
+  ids?: string[];
   all?: boolean;
 };
 
@@ -31,12 +32,29 @@ export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown
     );
   }
 
-  if (
-    (args.action === QUEST_ACTIONS.toggle ||
-      args.action === QUEST_ACTIONS.update ||
-      args.action === QUEST_ACTIONS.delete) &&
-    args.id !== undefined
-  ) {
+  if (args.action === QUEST_ACTIONS.toggle) {
+    if (args.ids && args.ids.length > 1) {
+      return new Text(`${actionText} ${theme.fg("muted", `[${args.ids.length} tasks]`)}`, 0, 0);
+    }
+
+    const toggleId = args.id ?? args.ids?.[0];
+    if (toggleId !== undefined) {
+      return new Text(`${actionText} ${theme.fg("muted", `[${toggleId}]`)}`, 0, 0);
+    }
+  }
+
+  if (args.action === QUEST_ACTIONS.delete) {
+    if (args.ids && args.ids.length > 1) {
+      return new Text(`${actionText} ${theme.fg("muted", `[${args.ids.length} tasks]`)}`, 0, 0);
+    }
+
+    const deleteId = args.id ?? args.ids?.[0];
+    if (deleteId !== undefined) {
+      return new Text(`${actionText} ${theme.fg("muted", `[${deleteId}]`)}`, 0, 0);
+    }
+  }
+
+  if (args.action === QUEST_ACTIONS.update && args.id !== undefined) {
     return new Text(`${actionText} ${theme.fg("muted", `[${args.id}]`)}`, 0, 0);
   }
 
@@ -59,8 +77,11 @@ export function renderQuestResult(config: ResolvedConfig) {
       isPartial: options.isPartial,
     });
     const details = result.details as Record<string, unknown> | undefined;
-    const allQuests = details?.quests as Quest[] | undefined;
-    const questsToRender = (details?.displayQuests ?? details?.quests) as Quest[] | undefined;
+    const snapshotQuests = details?.snapshotQuests as Quest[] | undefined;
+    const allQuests = (snapshotQuests ?? details?.quests) as Quest[] | undefined;
+    const questsToRender = (snapshotQuests ?? details?.displayQuests ?? details?.quests) as
+      | Quest[]
+      | undefined;
 
     if (
       !Array.isArray(questsToRender) ||

package/src/tools/handler.ts

@@ -1,17 +1,18 @@
-import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult, ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "typebox";
 import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
 import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "../prompts.js";
 import { makeToolResult, type QuestAction, type QuestLog } from "../quest/dataplane.js";
-import { QUEST_ACTIONS } from "../quest/types.js";
+import { QUEST_ACTIONS, type QuestActionType } from "../quest/types.js";
 
 const SPLIT_DISPLAY_ACTIONS = [
   QUEST_ACTIONS.add,
   QUEST_ACTIONS.list,
   QUEST_ACTIONS.split,
   QUEST_ACTIONS.add_step,
-  QUEST_ACTIONS.revert,
+  QUEST_ACTIONS.undo,
+  QUEST_ACTIONS.redo,
 ] as const;
 
 import { invalidateQuestListWidget } from "../renderers/commands.js";
@@ -20,75 +21,72 @@ import { createQuestParams, type QuestParamsType } from "./params.js";
 
 type QuestToolParams = Static<QuestParamsType>;
 
-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 ToolHandler = (
+  questLog: QuestLog,
+  params: QuestToolParams,
+  toolCallId: string,
+) => AgentToolResult<unknown>;
+
+const toolHandlers: Record<QuestActionType, ToolHandler> = {
+  [QUEST_ACTIONS.add]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.add,
       descriptions: params.descriptions,
-    });
-  },
-  [QUEST_ACTIONS.split](questLog, params, toolCallId) {
-    return runTool(questLog, toolCallId, {
+    }),
+  [QUEST_ACTIONS.split]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.split,
       id: params.id,
       descriptions: params.descriptions,
-    });
-  },
-  [QUEST_ACTIONS.add_step](questLog, params, toolCallId) {
-    return runTool(questLog, toolCallId, {
+    }),
+  [QUEST_ACTIONS.add_step]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.add_step,
       id: params.id,
       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, {
+    }),
+  [QUEST_ACTIONS.list]: (questLog, _params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.list }),
+  [QUEST_ACTIONS.toggle]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.toggle,
+      id: params.id,
+      ids: params.ids,
+    }),
+  [QUEST_ACTIONS.update]: (questLog, params, toolCallId) =>
+    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, all: params.all });
-  },
-  [QUEST_ACTIONS.reorder](questLog, params, toolCallId) {
-    return runTool(questLog, toolCallId, {
+    }),
+  [QUEST_ACTIONS.delete]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.delete,
+      id: params.id,
+      ids: params.ids,
+    }),
+  [QUEST_ACTIONS.clear]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.clear, all: params.all }),
+  [QUEST_ACTIONS.reorder]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.reorder,
       id: params.id,
       targetId: params.targetId,
-    });
-  },
-  [QUEST_ACTIONS.reparent](questLog, params, toolCallId) {
-    return runTool(questLog, toolCallId, {
+    }),
+  [QUEST_ACTIONS.reparent]: (questLog, params, toolCallId) =>
+    runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.reparent,
       id: params.id,
       parentId: params.parentId,
-    });
-  },
-  [QUEST_ACTIONS.rules](questLog, _params, toolCallId) {
-    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.rules });
-  },
-  [QUEST_ACTIONS.skill](questLog, _params, toolCallId) {
-    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.skill });
-  },
-  [QUEST_ACTIONS.revert](questLog, _params, toolCallId) {
-    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.revert });
-  },
+    }),
+  [QUEST_ACTIONS.rules]: (questLog, _params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.rules }),
+  [QUEST_ACTIONS.skill]: (questLog, _params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.skill }),
+  [QUEST_ACTIONS.undo]: (questLog, _params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.undo }),
+  [QUEST_ACTIONS.redo]: (questLog, _params, toolCallId) =>
+    runTool(questLog, toolCallId, { type: QUEST_ACTIONS.redo }),
 };
 
 function runTool(
@@ -104,11 +102,10 @@ function runTool(
     action.type as (typeof SPLIT_DISPLAY_ACTIONS)[number],
   )
     ? questLog.getAll()
-    : result.quest
-      ? [result.quest]
-      : undefined;
+    : (result.quests ?? (result.quest ? [result.quest] : []));
+  const snapshotQuests = action.type === QUEST_ACTIONS.delete ? displayQuests : undefined;
 
-  return makeToolResult(result.message, questLog, displayQuests);
+  return makeToolResult(result.message, questLog, displayQuests, snapshotQuests);
 }
 
 export async function questToolExecute(
@@ -116,8 +113,13 @@ export async function questToolExecute(
   toolCallId: string,
   params: QuestToolParams,
 ): Promise<AgentToolResult<unknown>> {
-  logger.debug("quests:tool", "execute", { toolCallId, action: params.action, id: params.id });
-  const handler = toolHandlers[params.action];
+  logger.debug("quests:tool", "execute", {
+    toolCallId,
+    action: params.action,
+    id: params.id,
+    ids: params.ids,
+  });
+  const handler = toolHandlers[params.action as QuestActionType];
   return handler(questLog, params, toolCallId);
 }
 
@@ -132,15 +134,43 @@ export function registerQuestTool(
     label: "Quest",
     description:
       "Manage the session quest log and retrieve the complete quest system documentation. " +
-      "Use this VERY frequently to track tasks, plans, and progress. " +
       "When you need to understand quests, steps, rules, or best practices, use action: 'skill' or action: 'rules'.",
     promptSnippet:
-      "Manage quests and steps, or retrieve quest rules and best practices via skill/rules",
+      "Manage quests and steps, or retrieve quest rules and best practices via skill/rules. " +
+      "Use this VERY frequently to track tasks, plans, and progress. ",
     promptGuidelines: [QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
     parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
       questToolExecute(questLog, toolCallId, params),
-    renderCall: renderQuestCall,
+    renderCall: renderQuestCall as unknown as (
+      args: object,
+      theme: Theme,
+      context: unknown,
+    ) => ReturnType<typeof renderQuestCall>,
+    renderResult: renderQuestResult(config),
+  });
+
+  pi.registerTool({
+    name: "learn_quests",
+    label: "Learn Quests",
+    description: "Learn about the quest system and how to use it effectively.",
+    promptSnippet: "Use this tool to learn about the quest system and how to use it effectively.",
+    promptGuidelines: [
+      "Use this tool when on a session to understand how and when to use quests.",
+      "ALWAYS run this tool when on a new session before starting any work.",
+    ],
+    parameters: Type.Object(
+      {},
+      { description: "No parameters required for learning about quests" },
+    ),
+    execute: async (_toolCallId, _params, _signal, _onUpdate, _ctx) =>
+      questToolExecute(questLog, "learn_quests", { action: QUEST_ACTIONS.skill }),
+    renderCall: ((_args: object, theme: Theme, context: unknown) =>
+      renderQuestCall({ action: QUEST_ACTIONS.skill }, theme, context)) as unknown as (
+      args: object,
+      theme: Theme,
+      context: unknown,
+    ) => ReturnType<typeof renderQuestCall>,
     renderResult: renderQuestResult(config),
   });
 }

package/src/tools/params.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@mariozechner/pi-ai";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 import { QUEST_ACTION_VALUES } from "../quest/types.js";
 
 export function createQuestParams(idLength: number) {
@@ -22,7 +22,13 @@ export function createQuestParams(idLength: number) {
     id: Type.Optional(
       Type.String({
         pattern,
-        description: `Quest ID (required for toggle, update, delete, reorder actions). ALWAYS use the ${idLength}-digit hex ID shown in brackets, never the positional number.`,
+        description: `Quest ID (required for update, reorder, and reparent actions. For toggle and delete, provide either id or ids. ALWAYS use the ${idLength}-digit hex ID shown in brackets, never the positional number.`,
+      }),
+    ),
+    ids: Type.Optional(
+      Type.Array(Type.String({ pattern }), {
+        minItems: 1,
+        description: `Quest IDs for batch toggle or delete actions. Use this when operating on more than one ${idLength}-digit hex quest ID at once.`,
       }),
     ),
     targetId: Type.Optional(