@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.11

package/src/task/worktree.ts

@@ -0,0 +1,69 @@
+// An environment "cloud" subagent is an isolated worker: a child process in its own git worktree on a new branch.
+import { execFile, execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/** Where a cloud subagent runs. Records and transcripts stay keyed on the parent workspace, never on this. */
+export interface Worktree {
+  /** The worktree root. */
+  path: string;
+  /** The child's working directory: the parent's place in the repository, mapped into the worktree. */
+  cwd: string;
+  branch: string;
+  /** The ref the branch starts from: origin/<cloud_base_branch>, cloud_base_branch, or HEAD. */
+  base: string;
+  commit: string;
+}
+
+function git(dir: string, args: readonly string[]): string {
+  return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+/** undefined when git ran and exited non-zero; a git that cannot start still throws. */
+function tryGit(dir: string, args: readonly string[]): string | undefined {
+  try {
+    return git(dir, args);
+  } catch (error) {
+    if (typeof (error as { status?: unknown }).status === 'number') return undefined;
+    throw error;
+  }
+}
+
+const commitOf = (dir: string, ref: string) => tryGit(dir, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+
+function resolveBase(cwd: string, baseBranch: string | undefined): { base: string; commit: string } {
+  if (baseBranch === undefined) {
+    const commit = commitOf(cwd, 'HEAD');
+    if (commit === undefined) throw new Error(`environment "cloud" branches the subagent's worktree from HEAD, but ${cwd} has no commits yet.`);
+    return { base: 'HEAD', commit };
+  }
+  // Cursor's cloud workers start from the pushed branch, so the remote-tracking ref wins over a local branch that may be
+  // behind it. A local-only branch or any other ref still works when no origin ref of that name exists.
+  for (const base of [`origin/${baseBranch}`, baseBranch]) {
+    const commit = commitOf(cwd, base);
+    if (commit !== undefined) return { base, commit };
+  }
+  throw new Error(`cloud_base_branch "${baseBranch}" names no commit in ${cwd}: neither origin/${baseBranch} nor ${baseBranch} exists. Pass an existing branch or omit cloud_base_branch to start from HEAD.`);
+}
+
+/** Resolves where a cloud agent will run without changing anything, so a bad base fails before any side effect. */
+export function planWorktree(cwd: string, worktreesDir: string, agentId: string, baseBranch?: string): Worktree {
+  const prefix = tryGit(cwd, ['rev-parse', '--show-prefix'])?.replace(/\/$/, '');
+  if (prefix === undefined) throw new Error(`environment "cloud" runs the subagent in its own git worktree, but ${cwd} is not inside a git repository. Omit environment to run the subagent here.`);
+  const { base, commit } = resolveBase(cwd, baseBranch);
+  const path = join(worktreesDir, agentId);
+  const inBase = prefix !== '' && tryGit(cwd, ['cat-file', '-e', `${commit}:${prefix}`]) !== undefined;
+  return { path, cwd: inBase ? join(path, prefix) : path, branch: `pstack/${agentId}`, base, commit };
+}
+
+/** Creates the worktree and its branch. Nothing here removes them: the parent merges the branch, and worktree-cleanup prunes. */
+export function addWorktree(repoDir: string, worktree: Worktree, signal: AbortSignal | undefined): Promise<void> {
+  // A checkout can run hooks and filters for a long time, so it runs off the event loop and stops with the Task call.
+  const args = ['-C', repoDir, 'worktree', 'add', '--quiet', '-b', worktree.branch, worktree.path, worktree.commit];
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { encoding: 'utf8', ...(signal === undefined ? {} : { signal }) }, (error, _stdout, stderr) => {
+      if (error === null) resolve();
+      else if (signal?.aborted === true) reject(new Error(`Stopped creating the subagent's worktree at ${worktree.path}.`));
+      else reject(new Error(`Could not create the subagent's worktree at ${worktree.path}: ${(stderr || error.message).trim()}`));
+    });
+  });
+}

package/src/todo.ts

@@ -0,0 +1,127 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+const STATUSES = ['pending', 'in_progress', 'completed', 'cancelled'] as const;
+type TodoStatus = (typeof STATUSES)[number];
+
+export interface TodoItem {
+  id: string;
+  content: string;
+  status: TodoStatus;
+}
+
+export interface TodoInput {
+  id: string;
+  content?: string;
+  status?: TodoStatus;
+}
+
+interface TodoDetails {
+  todos: TodoItem[];
+}
+
+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: '✗' };
+
+const TodoParams = Type.Object({
+  todos: Type.Array(
+    Type.Object({
+      id: Type.String({ description: 'Unique identifier for the TODO item' }),
+      content: Type.Optional(Type.String({ description: 'The description/content of the TODO item. Required for a new item; may be omitted when merging an update.' })),
+      status: Type.Optional(Type.Enum(STATUSES, { type: 'string', description: 'The current status of the TODO item. Required for a new item; may be omitted when merging an update.' })),
+    }),
+    { minItems: 1, description: 'Array of TODO items to update or create' },
+  ),
+  merge: Type.Boolean({
+    description:
+      'Whether to merge the todos with the existing todos. If true, the todos will be merged into the existing todos based on the id field. You can leave unchanged properties undefined. If false, the new todos will replace the existing todos.',
+  }),
+});
+
+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 };
+}
+
+/** TodoWrite: merge updates by id and appends new ids; otherwise the call replaces the list. */
+export function applyTodoWrite(current: readonly TodoItem[], todos: readonly TodoInput[], merge: boolean): TodoItem[] {
+  const seen = new Set<string>();
+  for (const item of todos) {
+    if (seen.has(item.id)) throw new Error(`Todo id "${item.id}" appears more than once in this call.`);
+    seen.add(item.id);
+  }
+  if (!merge) return todos.map((item) => complete(item, undefined));
+  const updates = new Map(todos.map((item) => [item.id, item]));
+  const merged = current.map((existing) => {
+    const update = updates.get(existing.id);
+    return update === undefined ? existing : complete(update, existing);
+  });
+  const known = new Set(current.map((item) => item.id));
+  return [...merged, ...todos.filter((item) => !known.has(item.id)).map((item) => complete(item, undefined))];
+}
+
+export function formatTodos(todos: readonly TodoItem[]): string {
+  if (todos.length === 0) return 'Todos: none.';
+  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');
+}
+
+interface BranchEntry {
+  type: string;
+  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: {}`. */
+export function todosFromBranch(entries: readonly BranchEntry[]): TodoItem[] {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const message = entries[index]?.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;
+  }
+  return [];
+}
+
+function widgetLines(todos: readonly TodoItem[]): string[] | undefined {
+  if (todos.length === 0) return undefined;
+  return [`Todos ${todos.filter((item) => item.status === 'completed').length}/${todos.length}`, ...todos.map((item) => `${GLYPHS[item.status]} ${item.content}`)];
+}
+
+/** The list as of the active branch, for the system prompt. Cursor keeps todos in conversation state; Pi keeps them here. */
+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 } {
+  let todos: TodoItem[] = [];
+  const show = (ctx: ExtensionContext) => {
+    if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, widgetLines(todos));
+  };
+  const restore = (ctx: ExtensionContext) => {
+    todos = todosFromBranch(ctx.sessionManager.getBranch());
+    show(ctx);
+  };
+  pi.on('session_start', (_event, ctx) => restore(ctx));
+  pi.on('session_tree', (_event, ctx) => restore(ctx));
+
+  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).',
+    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,
+    executionMode: 'sequential',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      todos = applyTodoWrite(todos, params.todos, params.merge);
+      show(ctx);
+      return { content: [{ type: 'text', text: formatTodos(todos) }], details: { todos } };
+    },
+  });
+  return { section: () => todoSection(todos) };
+}

package/src/visualize.ts

@@ -0,0 +1,244 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+
+export const MAX_POINTS = 500;
+export const MAX_SERIES = 32;
+
+const VisualizeParams = Type.Object({
+  title: Type.String({ description: 'Chart title.' }),
+  kind: Type.Union([Type.Literal('bar'), Type.Literal('line')], { description: 'bar: one bar per label and series. line: one line per series across the labels.' }),
+  labels: Type.Array(Type.String(), { description: `Category or x-axis labels, at most ${MAX_POINTS}.` }),
+  series: Type.Array(Type.Object({ name: Type.String(), values: Type.Array(Type.Number(), { description: 'One value per label.' }) }), { description: `One or more named series, at most ${MAX_SERIES}.` }),
+  unit: Type.Optional(Type.String({ description: 'Unit shown after values, such as ms or %.' })),
+});
+
+export type Chart = Static<typeof VisualizeParams>;
+
+/** The reason a chart cannot be drawn, or undefined when it can. */
+export function chartError(chart: Chart): string | undefined {
+  if (chart.labels.length === 0) return 'labels is empty: a chart needs at least one point.';
+  if (chart.series.length === 0) return 'series is empty: a chart needs at least one series.';
+  if (chart.series.length > MAX_SERIES) return `too many series: ${chart.series.length} series, at most ${MAX_SERIES}.`;
+  if (chart.labels.length > MAX_POINTS) return `too many points: ${chart.labels.length} labels, at most ${MAX_POINTS}.`;
+  for (const series of chart.series) {
+    if (series.values.length !== chart.labels.length) return `series "${series.name}" has ${series.values.length} values for ${chart.labels.length} labels; each series needs one value per label.`;
+    const bad = series.values.findIndex((value) => !Number.isFinite(value));
+    if (bad !== -1) return `series "${series.name}" value ${bad} (label "${chart.labels[bad]}") is ${series.values[bad]}, not a finite number.`;
+  }
+  return undefined;
+}
+
+export function formatValue(value: number, unit?: string): string {
+  const text = Number.isInteger(value) ? String(value) : String(Number(value.toPrecision(4)));
+  return unit === undefined || unit === '' ? text : `${text} ${unit}`;
+}
+
+const BAR_WIDTH = 40;
+const BAR_FILLS = ['█', '▓', '▒', '░'];
+const LINE_MARKS = ['●', '○', '◆', '◇', '■', '□', '▲', '△'];
+const PLOT_HEIGHT = 10;
+const PLOT_WIDTH = 60;
+
+function legend(chart: Chart, marks: readonly string[]): string[] {
+  return chart.series.length < 2 ? [] : ['', chart.series.map((series, index) => `${marks[index % marks.length]} ${series.name}`).join('  ')];
+}
+
+function maxAbs(chart: Chart): number {
+  let max = 0;
+  for (const series of chart.series) for (const value of series.values) max = Math.max(max, Math.abs(value));
+  return max;
+}
+
+function extent(values: Iterable<number>): { min: number; max: number } {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const value of values) {
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  return { min, max };
+}
+
+// A rendered chart is a validated chart: chartError rejected every series whose value count differs from the labels.
+function barText(chart: Chart): string[] {
+  const max = maxAbs(chart);
+  let labelWidth = 0;
+  for (const label of chart.labels) labelWidth = Math.max(labelWidth, label.length);
+  const lines: string[] = [];
+  chart.labels.forEach((label, point) => {
+    chart.series.forEach((series, index) => {
+      const value = series.values[point] as number;
+      const cells = max === 0 ? 0 : Math.max(value === 0 ? 0 : 1, Math.round((Math.abs(value) / max) * BAR_WIDTH));
+      const name = index === 0 ? label.padEnd(labelWidth) : ' '.repeat(labelWidth);
+      lines.push(`${name} │${(BAR_FILLS[index % BAR_FILLS.length] as string).repeat(cells)} ${formatValue(value, chart.unit)}`);
+    });
+  });
+  return [...lines, ...legend(chart, BAR_FILLS)];
+}
+
+function lineText(chart: Chart): string[] {
+  const { min, max } = extent(chart.series.flatMap((series) => series.values));
+  const columns = Math.min(PLOT_WIDTH, chart.labels.length);
+  const grid = Array.from({ length: PLOT_HEIGHT }, () => Array<string>(columns).fill(' '));
+  chart.series.forEach((series, index) => {
+    series.values.forEach((value, point) => {
+      const column = chart.labels.length === 1 ? 0 : Math.round((point / (chart.labels.length - 1)) * (columns - 1));
+      const row = max === min ? Math.floor(PLOT_HEIGHT / 2) : Math.round(((max - value) / (max - min)) * (PLOT_HEIGHT - 1));
+      (grid[row] as string[])[column] = LINE_MARKS[index % LINE_MARKS.length] as string;
+    });
+  });
+  const top = formatValue(max, chart.unit);
+  const bottom = formatValue(min, chart.unit);
+  const axisWidth = Math.max(top.length, bottom.length);
+  const rows = grid.map((cells, row) => {
+    const tick = row === 0 ? top : row === PLOT_HEIGHT - 1 ? bottom : '';
+    return `${tick.padStart(axisWidth)} ${row === 0 || row === PLOT_HEIGHT - 1 ? '┤' : '│'}${cells.join('')}`;
+  });
+  const first = chart.labels[0] as string;
+  const last = chart.labels.at(-1) as string;
+  const xLabels = chart.labels.length === 1 ? first : `${first}${' '.repeat(Math.max(1, columns - first.length - last.length))}${last}`;
+  return [...rows, `${' '.repeat(axisWidth)} └${'─'.repeat(columns)}`, `${' '.repeat(axisWidth + 2)}${xLabels}`, ...legend(chart, LINE_MARKS)];
+}
+
+/** The chart as Unicode text: the title, then the bars or the plot, then a legend when there is more than one series. */
+export function renderChartText(chart: Chart): string {
+  return [chart.title, '', ...(chart.kind === 'bar' ? barText(chart) : lineText(chart))].join('\n');
+}
+
+const PALETTE = ['#4e79a7', '#f28e2b', '#e15759', '#76b7b2', '#59a14f', '#edc948', '#b07aa1', '#ff9da7'];
+
+const XML_ESCAPES: Record<string, string> = { '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' };
+
+export function escapeXml(text: string): string {
+  return text.replace(/[<>&'"]/g, (char) => XML_ESCAPES[char] as string);
+}
+
+const round = (value: number) => Math.round(value * 100) / 100;
+
+/** A self-contained SVG of the chart: title, labeled axes with ticks, and a legend. */
+export function renderChartSvg(chart: Chart): string {
+  const width = 800;
+  const height = 450;
+  const margin = { top: 60, right: 30, bottom: 80, left: 80 };
+  const plotWidth = width - margin.left - margin.right;
+  const plotHeight = height - margin.top - margin.bottom;
+  const values = chart.series.flatMap((series) => series.values);
+  let { min, max } = extent(values);
+  if (chart.kind === 'bar') {
+    min = Math.min(min, 0);
+    max = Math.max(max, 0);
+  }
+  if (min === max) {
+    min -= 1;
+    max += 1;
+  }
+  const y = (value: number) => round(margin.top + ((max - value) / (max - min)) * plotHeight);
+  const count = chart.labels.length;
+  const band = plotWidth / count;
+  const xCenter = (point: number) => round(margin.left + (chart.kind === 'bar' || count === 1 ? band * (point + 0.5) : (point / (count - 1)) * plotWidth));
+  const parts: string[] = [];
+
+  parts.push(`<text x="${width / 2}" y="30" text-anchor="middle" font-size="18" font-weight="bold">${escapeXml(chart.title)}</text>`);
+  const ticks = 5;
+  for (let tick = 0; tick <= ticks; tick += 1) {
+    const value = min + ((max - min) * tick) / ticks;
+    parts.push(`<line x1="${margin.left}" y1="${y(value)}" x2="${width - margin.right}" y2="${y(value)}" stroke="#e0e0e0"/>`);
+    parts.push(`<text x="${margin.left - 8}" y="${y(value) + 4}" text-anchor="end" font-size="11">${escapeXml(formatValue(value, chart.unit))}</text>`);
+  }
+  parts.push(`<line x1="${margin.left}" y1="${margin.top}" x2="${margin.left}" y2="${margin.top + plotHeight}" stroke="#333"/>`);
+  parts.push(`<line x1="${margin.left}" y1="${y(Math.max(min, Math.min(0, max)))}" x2="${width - margin.right}" y2="${y(Math.max(min, Math.min(0, max)))}" stroke="#333"/>`);
+  const labelEvery = Math.max(1, Math.ceil(count / 20));
+  chart.labels.forEach((label, point) => {
+    if (point % labelEvery === 0) {
+      const x = xCenter(point);
+      const labelY = margin.top + plotHeight + 16;
+      parts.push(`<text x="${x}" y="${labelY}" text-anchor="end" font-size="11" transform="rotate(-30 ${x} ${labelY})">${escapeXml(label)}</text>`);
+    }
+  });
+  if (chart.unit !== undefined && chart.unit !== '')
+    parts.push(`<text x="18" y="${margin.top + plotHeight / 2}" text-anchor="middle" font-size="12" transform="rotate(-90 18 ${margin.top + plotHeight / 2})">${escapeXml(chart.unit)}</text>`);
+
+  chart.series.forEach((series, index) => {
+    const color = PALETTE[index % PALETTE.length];
+    if (chart.kind === 'bar') {
+      const barWidth = (band * 0.8) / chart.series.length;
+      series.values.forEach((value, point) => {
+        const x = round(margin.left + band * point + band * 0.1 + barWidth * index);
+        const top = Math.min(y(value), y(0));
+        parts.push(
+          `<rect x="${x}" y="${top}" width="${round(barWidth)}" height="${round(Math.abs(y(value) - y(0)))}" fill="${color}"><title>${escapeXml(`${series.name} ${chart.labels[point]}: ${formatValue(value, chart.unit)}`)}</title></rect>`,
+        );
+      });
+    } else {
+      const points = series.values.map((value, point) => `${xCenter(point)},${y(value)}`).join(' ');
+      parts.push(`<polyline points="${points}" fill="none" stroke="${color}" stroke-width="2"/>`);
+      if (count <= 60)
+        series.values.forEach((value, point) => {
+          parts.push(`<circle cx="${xCenter(point)}" cy="${y(value)}" r="3" fill="${color}"/>`);
+        });
+    }
+  });
+
+  chart.series.forEach((series, index) => {
+    const x = margin.left + index * 150;
+    parts.push(`<rect x="${x}" y="42" width="12" height="12" fill="${PALETTE[index % PALETTE.length]}"/>`);
+    parts.push(`<text x="${x + 18}" y="52" font-size="12">${escapeXml(series.name)}</text>`);
+  });
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="sans-serif">`,
+    `<rect width="${width}" height="${height}" fill="#ffffff"/>`,
+    ...parts,
+    '</svg>',
+    '',
+  ].join('\n');
+}
+
+export function chartSlug(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+    .replace(/-+$/, '');
+  return slug === '' ? 'chart' : slug;
+}
+
+function timestamp(date: Date): string {
+  return date
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d+Z$/, 'Z');
+}
+
+export interface VisualizeOptions {
+  artifactsDir: (ctx: ExtensionContext) => string;
+  now?: () => Date;
+}
+
+export function registerVisualize(pi: ExtensionAPI, options: VisualizeOptions): void {
+  pi.registerTool({
+    name: 'visualize',
+    label: 'Visualize',
+    description: 'Draw a bar or line chart from labels and one or more named series. The result shows the chart as Unicode text and names an SVG file written to the session artifacts folder.',
+    promptSnippet: 'Draw a bar or line chart (Unicode in the result, SVG file in the artifacts folder)',
+    parameters: VisualizeParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const error = chartError(params);
+      if (error !== undefined) throw new Error(`visualize: ${error}`);
+      const dir = options.artifactsDir(ctx);
+      mkdirSync(dir, { recursive: true });
+      const stamp = timestamp((options.now ?? (() => new Date()))());
+      const slug = chartSlug(params.title);
+      let path = join(dir, `${stamp}-${slug}.svg`);
+      for (let n = 2; existsSync(path); n += 1) path = join(dir, `${stamp}-${slug}-${n}.svg`);
+      writeFileSync(path, renderChartSvg(params));
+      return { content: [{ type: 'text', text: `${renderChartText(params)}\n\nSVG: ${path}` }], details: { path } };
+    },
+  });
+}