pi-quests 0.3.0 → 0.5.0

package/src/renderers/tools.ts

@@ -1,18 +1,26 @@
 import type { AgentToolResult, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
+import type { Quest } from "../quest/types.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
+import { formatQuestRow, formatStepSpacerLine } from "./quests.js";
 
 type QuestArgs = {
   action: string;
   descriptions?: string[];
-  id?: number;
+  targetId?: string;
+  id?: string;
+  all?: boolean;
 };
 
 export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown): Text {
   const id = "id" in args ? args.id : undefined;
   logger.debug("quests:tool", "renderCall", { action: args.action, id });
-  const actionText = theme.fg("toolTitle", theme.bold("quest ")) + theme.fg("accent", args.action);
+  const actionText =
+    theme.fg("toolTitle", theme.bold("quest ")) +
+    theme.fg("accent", args.action) +
+    theme.fg("muted", args.targetId ? ` ${args.targetId}` : "");
 
   if (args.action === QUEST_ACTIONS.add && args.descriptions && args.descriptions.length > 0) {
     const n = args.descriptions.length;
@@ -29,41 +37,82 @@ export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown
       args.action === QUEST_ACTIONS.delete) &&
     args.id !== undefined
   ) {
-    return new Text(`${actionText} ${theme.fg("muted", `#${args.id}`)}`, 0, 0);
+    return new Text(`${actionText} ${theme.fg("muted", `[${args.id}]`)}`, 0, 0);
+  }
+
+  if (args.action === QUEST_ACTIONS.clear) {
+    return new Text(`${actionText} ${theme.fg("muted", `[${args.all ? "all" : "done"}]`)}`, 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 Record<string, unknown> | undefined;
-  const allQuests =
-    (details?.quests as Array<{ id: number; description: string; done: boolean }> | undefined) ??
-    [];
-  const questsToRender = (details?.displayQuests ?? details?.quests) as
-    | Array<{ id: number; description: string; done: boolean }>
-    | undefined;
-
-  if (Array.isArray(questsToRender) && questsToRender.length > 0) {
-    const lines = questsToRender.map((q) => {
-      const pos = allQuests.findIndex((x) => x.id === q.id) + 1 || 1;
-      const marker = q.done ? theme.fg("success", "✓") : theme.fg("dim", "○");
-
-      return `${marker} ${theme.fg("text", `#${pos}`)} ${theme.fg("muted", q.description)}`;
+export function renderQuestResult(config: ResolvedConfig) {
+  return (
+    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 Record<string, unknown> | undefined;
+    const allQuests = details?.quests as Quest[] | undefined;
+    const questsToRender = (details?.displayQuests ?? details?.quests) as Quest[] | undefined;
 
-    return new Text(lines.join("\n"), 0, 0);
-  }
+    if (
+      !Array.isArray(questsToRender) ||
+      questsToRender.length === 0 ||
+      !Array.isArray(allQuests)
+    ) {
+      const text = result.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("\n");
+      return new Text(theme.fg("text", text), 0, 0);
+    }
+
+    const quests = allQuests;
+    const renderedIds = new Set(questsToRender.map((q) => q.id));
+    const parents = quests.filter((q) => !(q as Quest & { parentId?: string }).parentId);
+    const lines: string[] = [];
+
+    function getSteps(parentId: string) {
+      return quests.filter((q) => (q as Quest & { parentId?: string }).parentId === parentId);
+    }
+
+    function willRenderLater(idx: number): boolean {
+      for (let j = idx + 1; j < parents.length; j++) {
+        const p = parents[j];
+        if (renderedIds.has(p.id)) return true;
+
+        const steps = getSteps(p.id).filter((step) => renderedIds.has(step.id));
+        if (steps.length > 0) return true;
+      }
 
-  const text = result.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("\n");
-  return new Text(theme.fg("text", text), 0, 0);
+      return false;
+    }
+
+    for (let i = 0; i < parents.length; i++) {
+      const parent = parents[i];
+      const parentIncluded = renderedIds.has(parent.id);
+      const includedSteps = getSteps(parent.id).filter((step) => renderedIds.has(step.id));
+
+      if (!parentIncluded && includedSteps.length === 0) continue;
+
+      if (parentIncluded) {
+        lines.push(formatQuestRow(theme, parent, config.ids.length, i + 1));
+        if (includedSteps.length > 0) lines.push(formatStepSpacerLine(theme, config.ids.length));
+      }
+
+      for (const step of includedSteps) {
+        lines.push(formatQuestRow(theme, step, config.ids.length));
+      }
+
+      if (includedSteps.length > 0 && willRenderLater(i)) {
+        lines.push("");
+      }
+    }
+
+    return new Text(lines.join("\n"), 0, 0);
+  };
 }

package/src/tools/handler.ts

@@ -1,13 +1,23 @@
 import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { Static } from "@sinclair/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";
+
+const SPLIT_DISPLAY_ACTIONS = [
+  QUEST_ACTIONS.add,
+  QUEST_ACTIONS.list,
+  QUEST_ACTIONS.split,
+  QUEST_ACTIONS.add_step,
+  QUEST_ACTIONS.revert,
+] as const;
+
 import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
-import { QuestParams } from "./params.js";
+import { createQuestParams, type QuestParamsType } from "./params.js";
 
-type QuestToolParams = Static<typeof QuestParams>;
+type QuestToolParams = Static<QuestParamsType>;
 
 const toolHandlers: {
   [K in QuestToolParams["action"]]: (
@@ -22,6 +32,20 @@ const toolHandlers: {
       descriptions: params.descriptions,
     });
   },
+  [QUEST_ACTIONS.split](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.split,
+      id: params.id,
+      descriptions: params.descriptions,
+    });
+  },
+  [QUEST_ACTIONS.add_step](questLog, params, toolCallId) {
+    return 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 });
   },
@@ -45,9 +69,22 @@ const toolHandlers: {
     return runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.reorder,
       id: params.id,
-      targetIndex: params.targetIndex,
+      targetId: params.targetId,
     });
   },
+  [QUEST_ACTIONS.reparent](questLog, params, toolCallId) {
+    return 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 });
   },
@@ -61,14 +98,13 @@ function runTool(
   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;
+  const displayQuests = SPLIT_DISPLAY_ACTIONS.includes(
+    action.type as (typeof SPLIT_DISPLAY_ACTIONS)[number],
+  )
+    ? questLog.getAll()
+    : result.quest
+      ? [result.quest]
+      : undefined;
 
   return makeToolResult(result.message, questLog, displayQuests);
 }
@@ -83,19 +119,26 @@ export async function questToolExecute(
   return handler(questLog, params, toolCallId);
 }
 
-export function registerQuestTool(pi: ExtensionAPI, questLog: QuestLog): void {
+export function registerQuestTool(
+  pi: ExtensionAPI,
+  questLog: QuestLog,
+  config: ResolvedConfig,
+): 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",
+      "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",
     promptGuidelines: [...QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
-    parameters: QuestParams,
+    parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
       questToolExecute(questLog, toolCallId, params),
     renderCall: renderQuestCall,
-    renderResult: renderQuestResult,
+    renderResult: renderQuestResult(config),
   });
 }

package/src/tools/params.ts

@@ -2,34 +2,48 @@ 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)",
+export function createQuestParams(idLength: number) {
+  const pattern = `^[0-9a-f]{${idLength}}$`;
+  return Type.Object({
+    action: StringEnum(QUEST_ACTION_VALUES, {
+      description: "The quest action to perform",
     }),
-  ),
-  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, reorder actions)",
-    }),
-  ),
-  targetIndex: Type.Optional(
-    Type.Number({
-      description:
-        "Target index for reorder action (0-based array index). If moving to the 3rd slot in the list, use 2.",
-    }),
-  ),
-  all: Type.Optional(
-    Type.Boolean({
-      description: "Clear all quests when true (defaults to clearing only completed quests)",
-    }),
-  ),
-});
+    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.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.`,
+      }),
+    ),
+    targetId: Type.Optional(
+      Type.String({
+        pattern,
+        description:
+          "Target quest ID for reorder action. The quest will be moved to just before the target quest.",
+      }),
+    ),
+    parentId: Type.Optional(
+      Type.String({
+        pattern,
+        description: "Parent quest ID for reparent action. Omit to promote to top-level.",
+      }),
+    ),
+    all: Type.Optional(
+      Type.Boolean({
+        description: "Clear all quests when true (defaults to clearing only completed quests)",
+      }),
+    ),
+  });
+}
+
+export type QuestParamsType = ReturnType<typeof createQuestParams>;