@justjoshn/pi-pstack 0.15.36-pi.11 → 0.15.36-pi.13

package/src/todo.ts

@@ -8,18 +8,21 @@ export interface TodoItem {
   id: string;
   content: string;
   status: TodoStatus;
+  dependencies?: string[];
 }
 
 export interface TodoInput {
   id: string;
   content?: string;
   status?: TodoStatus;
+  dependencies?: string[];
 }
 
 interface TodoDetails {
   todos: TodoItem[];
 }
 
+const TODO_ENTRY = 'pstack/todos';
 const WIDGET_KEY = 'pstack-todos';
 const MARKS: Record<TodoStatus, string> = { pending: '[ ]', in_progress: '[>]', completed: '[x]', cancelled: '[-]' };
 const GLYPHS: Record<TodoStatus, string> = { pending: '○', in_progress: '▶', completed: '✓', cancelled: '✗' };
@@ -43,7 +46,8 @@ function complete(item: TodoInput, existing: TodoItem | undefined): TodoItem {
   const content = item.content ?? existing?.content;
   const status = item.status ?? existing?.status;
   if (content === undefined || status === undefined) throw new Error(`Todo "${item.id}" is new, so it needs both content and status.`);
-  return { id: item.id, content, status };
+  const dependencies = item.dependencies ?? existing?.dependencies;
+  return { id: item.id, content, status, ...(dependencies === undefined ? {} : { dependencies }) };
 }
 
 /** TodoWrite: merge updates by id and appends new ids; otherwise the call replaces the list. */
@@ -68,18 +72,25 @@ export function formatTodos(todos: readonly TodoItem[]): string {
   const done = todos.filter((item) => item.status === 'completed').length;
   const active = todos.filter((item) => item.status === 'in_progress').length;
   const header = `Todos (${done}/${todos.length} completed${active > 0 ? `, ${active} in progress` : ''}):`;
-  return [header, ...todos.map((item) => `${MARKS[item.status]} ${item.id}: ${item.content}`)].join('\n');
+  return [header, ...todos.map((item) => `${MARKS[item.status]} ${item.id}: ${item.content}${item.dependencies === undefined || item.dependencies.length === 0 ? '' : ` (depends on ${item.dependencies.join(', ')})`}`)].join('\n');
 }
 
 interface BranchEntry {
   type: string;
+  customType?: string;
+  data?: unknown;
   message?: { role?: string; toolName?: string; isError?: boolean; details?: unknown };
 }
 
-/** The list as of the active branch: the details of the last successful TodoWrite on it. A failed call stores `details: {}`. */
+/** The list as of the active branch, from a plan import or the last successful TodoWrite. */
 export function todosFromBranch(entries: readonly BranchEntry[]): TodoItem[] {
   for (let index = entries.length - 1; index >= 0; index -= 1) {
-    const message = entries[index]?.message;
+    const entry = entries[index];
+    if (entry?.type === 'custom' && entry.customType === TODO_ENTRY) {
+      const todos = (entry.data as Partial<TodoDetails> | undefined)?.todos;
+      if (Array.isArray(todos)) return todos;
+    }
+    const message = entry?.message;
     const todos = (message?.details as Partial<TodoDetails> | undefined)?.todos;
     if (entries[index]?.type === 'message' && message?.role === 'toolResult' && message.toolName === 'TodoWrite' && message.isError !== true && Array.isArray(todos)) return todos;
   }
@@ -96,7 +107,27 @@ export function todoSection(todos: readonly TodoItem[]): string | undefined {
   return todos.length === 0 ? undefined : `Current todo list, owned by this session:\n${formatTodos(todos)}`;
 }
 
-export function registerTodoWrite(pi: ExtensionAPI): { section: () => string | undefined } {
+// Cursor's TodoWrite rules: when to keep a list, the four states, one task in progress at a time, and batching.
+const TODO_DESCRIPTION = [
+  'Use this tool to create and manage a structured task list for your current coding session. It tracks progress, organizes complex tasks, and shows the user what you are doing. Each item has an id, content, and status.',
+  '',
+  'Other than when you first create the list, do not tell the user you are updating todos. Just update them.',
+  '',
+  'Use it for:',
+  '- A task with three or more distinct steps, or non-trivial work that needs planning.',
+  '- An explicit request for a todo list, or several tasks given at once (numbered or comma-separated).',
+  '- New instructions: capture the requirements as todos.',
+  '- A finished task: mark it completed (merge=true) and add any follow-ups.',
+  '- A task you start: mark it in_progress.',
+  '',
+  'Skip it for a single straightforward task, a trivial task done in fewer than three steps, or a purely conversational or informational request. Do not add a task to test a change unless asked.',
+  '',
+  'States: pending (not started), in_progress (working on it now), completed (finished), cancelled (no longer needed). Update states as you work, mark a task completed as soon as it is done, keep only one task in_progress at a time, and finish the current task before you start a new one. Write specific, actionable items with clear names.',
+  '',
+  'Prefer creating the first todo as in_progress, and start on it with tool calls in the same batch as the write. Batch todo updates with your other tool calls.',
+].join('\n');
+
+export function registerTodoWrite(pi: ExtensionAPI, options: { onWrite?: (todos: readonly TodoItem[]) => void } = {}) {
   let todos: TodoItem[] = [];
   const show = (ctx: ExtensionContext) => {
     if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, widgetLines(todos));
@@ -111,7 +142,7 @@ export function registerTodoWrite(pi: ExtensionAPI): { section: () => string | u
   pi.registerTool({
     name: 'TodoWrite',
     label: 'Todos',
-    description: 'Use this tool to create and manage a structured task list for your current coding session. Each item has an id, content, and status (pending, in_progress, completed, cancelled).',
+    description: TODO_DESCRIPTION,
     promptSnippet: 'Create and update the todo list for this session',
     promptGuidelines: ['When a skill or playbook says to open a todolist or todo list, call TodoWrite before other work, with the steps it names as the first items.'],
     parameters: TodoParams,
@@ -119,9 +150,21 @@ export function registerTodoWrite(pi: ExtensionAPI): { section: () => string | u
     annotations: { readOnlyHint: true, openWorldHint: false },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       todos = applyTodoWrite(todos, params.todos, params.merge);
+      try {
+        options.onWrite?.(todos);
+      } catch (error) {
+        ctx.ui.notify(`The todo list was updated, but its plan file could not be synchronized: ${error instanceof Error ? error.message : String(error)}`, 'warning');
+      }
       show(ctx);
       return { content: [{ type: 'text', text: formatTodos(todos) }], details: { todos } };
     },
   });
-  return { section: () => todoSection(todos) };
+  return {
+    section: () => todoSection(todos),
+    replace: (items: readonly TodoItem[], ctx: ExtensionContext) => {
+      todos = applyTodoWrite([], items, false);
+      pi.appendEntry(TODO_ENTRY, { todos });
+      show(ctx);
+    },
+  };
 }

package/src/path-skills.ts

@@ -1,104 +0,0 @@
-// Cursor attaches a skill to the conversation when the agent reads a file matching its `paths`/`globs` frontmatter.
-// Pi has no path-scoped skills, so this module tracks the files a session reads or edits and attaches the matching
-// skill body once per session, in the same <skill> block shape Pi's own /skill:name expansion uses.
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, isAbsolute, matchesGlob, relative, sep } from 'node:path';
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
-
-/** A skill whose frontmatter scopes it to file patterns. */
-export interface PathSkill {
-  name: string;
-  file: string;
-  globs: string[];
-  body: string;
-}
-
-const TOUCHED_TOOLS = new Set(['read', 'edit', 'write']);
-const SECTION_LIMIT = 40_000;
-
-function globsOf(value: unknown): string[] {
-  if (typeof value === 'string')
-    return value
-      .split(',')
-      .map((part) => part.trim())
-      .filter((part) => part !== '');
-  if (!Array.isArray(value)) return [];
-  return value.filter((part): part is string => typeof part === 'string' && part.trim() !== '').map((part) => part.trim());
-}
-
-/** Every loaded skill that declares `paths` (Cursor's name for skill globs) or `globs`. */
-export function loadPathSkills(commands: readonly { name: string; source: string; sourceInfo: { path: string } }[]): PathSkill[] {
-  const skills: PathSkill[] = [];
-  for (const command of commands) {
-    if (command.source !== 'skill' || !command.name.startsWith('skill:')) continue;
-    const file = command.sourceInfo.path;
-    if (!existsSync(file)) continue;
-    const { frontmatter, body } = parseFrontmatter(readFileSync(file, 'utf8'));
-    // `metadata` is the portable Agent Skills extension point; Cursor's own field is the top-level `paths`/`globs`.
-    const metadata = typeof frontmatter['metadata'] === 'object' && frontmatter['metadata'] !== null ? (frontmatter['metadata'] as Record<string, unknown>) : {};
-    const globs = [...new Set([...globsOf(frontmatter['paths']), ...globsOf(frontmatter['globs']), ...globsOf(metadata['paths']), ...globsOf(metadata['globs'])])];
-    if (globs.length === 0) continue;
-    skills.push({ name: command.name.slice('skill:'.length), file, globs, body: body.trim() });
-  }
-  return skills;
-}
-
-const slash = (path: string) => path.split(sep).join('/');
-
-/** The skills whose patterns match a path the session read or edited. Paths outside the workspace are ignored. */
-export function matchPathSkills(skills: readonly PathSkill[], paths: Iterable<string>, cwd: string): PathSkill[] {
-  const relativePaths = [...paths].map((path) => slash(isAbsolute(path) ? relative(cwd, path) : path)).filter((path) => path !== '' && path !== '..' && !path.startsWith('../'));
-  return skills.filter((skill) => relativePaths.some((path) => skill.globs.some((glob) => matchesGlob(path, glob))));
-}
-
-/** The attached bodies as <skill> blocks, in the shape Pi's /skill:name expansion builds. */
-export function pathSkillsSection(skills: readonly PathSkill[]): string | undefined {
-  if (skills.length === 0) return undefined;
-  const blocks: string[] = [];
-  let size = 0;
-  for (const skill of skills) {
-    const block = [`<skill name="${skill.name}" location="${skill.file}">`, `References are relative to ${dirname(skill.file)}.`, '', skill.body, '</skill>'].join('\n');
-    if (size + block.length > SECTION_LIMIT) break;
-    size += block.length;
-    blocks.push(block);
-  }
-  return blocks.length === 0 ? undefined : blocks.join('\n\n');
-}
-
-export interface PathSkillsHandle {
-  /** The skills to attach to the next request, empty until a matching file has been read or edited. */
-  section: () => string | undefined;
-}
-
-/** Tracks read and edit paths and attaches each matching skill once per session. */
-export function createPathSkills(pi: ExtensionAPI): PathSkillsHandle {
-  let catalog: PathSkill[] | undefined;
-  let cwd = process.cwd();
-  let touched = new Set<string>();
-  const injected = new Set<string>();
-
-  pi.on('session_start', (_event, ctx) => {
-    catalog = undefined;
-    touched = new Set();
-    injected.clear();
-    cwd = ctx.cwd;
-  });
-  pi.on('tool_call', (event) => {
-    if (!TOUCHED_TOOLS.has(event.toolName)) return;
-    const path = (event.input as { path?: unknown }).path;
-    if (typeof path === 'string' && path !== '') touched.add(path);
-  });
-
-  return {
-    section: () => {
-      if (touched.size === 0) return undefined;
-      catalog ??= loadPathSkills(pi.getCommands());
-      const matches = matchPathSkills(catalog, touched, cwd).filter((skill) => !injected.has(skill.name));
-      if (matches.length === 0) return undefined;
-      for (const skill of matches) injected.add(skill.name);
-      return pathSkillsSection(matches);
-    },
-  };
-}