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

package/src/todo.ts

@@ -0,0 +1,122 @@
+import { StringEnum } from '@earendil-works/pi-ai';
+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(StringEnum(STATUSES, { 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}`)];
+}
+
+export function registerTodoWrite(pi: ExtensionAPI): void {
+  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 } };
+    },
+  });
+}

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 } };
+    },
+  });
+}

package/test/aliases.test.ts

@@ -0,0 +1,57 @@
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'vitest';
+import { aliasInputResult, aliasTable, aliasTransform, packageSkillNames } from '../src/aliases.ts';
+import { SKILLS_DIR } from '../src/paths.ts';
+
+const names = new Set(['how', 'poteto-mode', 'principle-prove-it-works']);
+
+describe('aliasTransform', () => {
+  test.for([
+    { input: '/how', expected: '/skill:how' },
+    { input: '/how does the cache work?', expected: '/skill:how does the cache work?' },
+    { input: '/poteto-mode fix the "drift" bug\nrepro first, then $1 and $@', expected: '/skill:poteto-mode fix the "drift" bug\nrepro first, then $1 and $@' },
+    { input: '/how\nwhat owns retries?', expected: '/skill:how \nwhat owns retries?' },
+    { input: '/principle-prove-it-works', expected: '/skill:principle-prove-it-works' },
+  ])('rewrites $input to a native skill command (CMD-001)', ({ input, expected }) => {
+    expect(aliasTransform(input, names)).toBe(expected);
+  });
+
+  test.for([
+    { input: '/skill:how what', why: 'already native' },
+    { input: '/model', why: 'a Pi built-in' },
+    { input: '/howdy partner', why: 'a longer word that only starts with a skill name' },
+    { input: '/unknown thing', why: 'not a shipped skill' },
+    { input: 'please /how this', why: 'not at the start' },
+    { input: ' /how leading space', why: 'Pi commands start at column zero' },
+    { input: '', why: 'empty input' },
+  ])('leaves $why input alone (CMD-002)', ({ input }) => {
+    expect(aliasInputResult({ text: input }, names)).toEqual({ action: 'continue' });
+  });
+
+  test('the input handler transforms an alias and keeps attached images (CMD-001)', () => {
+    const images = [{ type: 'image' as const, data: 'AAAA', mimeType: 'image/png' }];
+    expect(aliasInputResult({ text: '/how this screen?', images }, names)).toEqual({ action: 'transform', text: '/skill:how this screen?', images });
+  });
+});
+
+describe('aliasTable (CMD-002, CMD-003; review: architecture 6)', () => {
+  const skill = (name: string, path: string) => ({ name: `skill:${name}`, description: `${name} skill`, source: 'skill' as const, sourceInfo: { path, source: 'test', scope: 'user' as const, origin: 'package' as const } });
+  const commands = [
+    skill('how', join(SKILLS_DIR, 'how/SKILL.md')),
+    skill('why', join(SKILLS_DIR, 'why/SKILL.md')),
+    skill('mine', '/home/me/.pi/agent/skills/mine/SKILL.md'),
+    { name: 'why', description: 'user template', source: 'prompt' as const, sourceInfo: { path: '/home/me/.pi/agent/prompts/why.md', source: 'test', scope: 'user' as const, origin: 'top-level' as const } },
+  ];
+
+  test('aliases every loaded skill that no template or command already names, as Cursor attaches any skill by /name (review r2: parity 1)', () => {
+    expect([...aliasTable(commands)]).toEqual([
+      ['how', 'how skill'],
+      ['mine', 'mine skill'],
+    ]);
+  });
+
+  test('lists the loaded skills that live in this package, by canonical path (A4, recheck 1)', () => {
+    expect(packageSkillNames(commands)).toEqual(['how', 'why']);
+  });
+});

package/test/ask.test.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { Static } from 'typebox';
+import { Value } from 'typebox/value';
+import { describe, expect, test } from 'vitest';
+import { AskParams, DONE_LABEL, validateQuestions } from '../src/ask.ts';
+
+const question = (options: { id: string; label: string }[], allow_multiple?: boolean) => ({ id: 'q', prompt: 'Pick', options, ...(allow_multiple === undefined ? {} : { allow_multiple }) });
+const outcome = (questions: ReturnType<typeof question>[]) => {
+  try {
+    validateQuestions(questions);
+    return 'valid';
+  } catch (error) {
+    return (error as Error).message;
+  }
+};
+
+describe('validateQuestions (HOST-005; reviews: parity, security 6, architecture 4)', () => {
+  test.for([
+    {
+      name: 'duplicate labels',
+      questions: [
+        question([
+          { id: 'a', label: 'Same' },
+          { id: 'b', label: 'Same' },
+        ]),
+      ],
+      expected: 'Question "q" has two options labelled "Same".',
+    },
+    {
+      name: 'duplicate option ids',
+      questions: [
+        question([
+          { id: 'a', label: 'A' },
+          { id: 'a', label: 'B' },
+        ]),
+      ],
+      expected: 'Question "q" has two options with id "a".',
+    },
+    { name: 'no options', questions: [question([])], expected: 'Question "q" has no options.' },
+    { name: 'the reserved other id', questions: [question([{ id: 'other', label: 'Something else' }])], expected: 'Option label "Other: (type to answer)" and id "other" are reserved for the typed answer.' },
+    { name: 'the reserved done label', questions: [question([{ id: 'd', label: DONE_LABEL }], true)], expected: `Option label "${DONE_LABEL}" is reserved for ending a multi-select question.` },
+    {
+      name: 'a well-formed question',
+      questions: [
+        question(
+          [
+            { id: 'a', label: 'Done' },
+            { id: 'b', label: 'B' },
+          ],
+          true,
+        ),
+      ],
+      expected: 'valid',
+    },
+  ])('$name', ({ questions, expected }) => {
+    expect(outcome(questions)).toBe(expected);
+  });
+});
+
+describe('Cursor AskQuestion calls (HOST-005)', () => {
+  // 24 AskQuestion inputs the Cursor IDE produced, read from its agent transcripts.
+  const fixture = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'fixtures/cursor-askquestion-calls.json'), 'utf8')) as { calls: { input: Static<typeof AskParams> }[] };
+  const questionSchema = AskParams.properties.questions.items;
+  const optionSchema = questionSchema.properties.options.items;
+
+  test('every field Cursor sends is declared by the port schema', () => {
+    const undeclared = fixture.calls.flatMap(({ input }) => [
+      ...Object.keys(input).filter((key) => !(key in AskParams.properties)),
+      ...input.questions.flatMap((question) => [
+        ...Object.keys(question).filter((key) => !(key in questionSchema.properties)),
+        ...question.options.flatMap((option) => Object.keys(option).filter((key) => !(key in optionSchema.properties))),
+      ]),
+    ]);
+    expect(fixture.calls.length).toBe(24);
+    expect(undeclared).toEqual([]);
+  });
+
+  test('every Cursor call is valid input for the port', () => {
+    expect(fixture.calls.filter(({ input }) => !Value.Check(AskParams, input))).toEqual([]);
+    expect(fixture.calls.map(({ input }) => outcome(input.questions as ReturnType<typeof question>[]))).toEqual(fixture.calls.map(() => 'valid'));
+  });
+});

package/test/autocomplete.test.ts

@@ -0,0 +1,39 @@
+import type { AutocompleteItem, AutocompleteProvider } from '@earendil-works/pi-tui';
+import { describe, expect, test } from 'vitest';
+import { aliasAutocomplete } from '../src/autocomplete.ts';
+
+const builtin: AutocompleteItem[] = [
+  { value: 'skill:poteto-mode', label: 'skill:poteto-mode' },
+  { value: 'model', label: 'model' },
+];
+const current: AutocompleteProvider = {
+  getSuggestions: async (lines, _line, col) => ((lines[0] ?? '').slice(0, col).startsWith('/') ? { items: builtin, prefix: (lines[0] ?? '').slice(0, col) } : null),
+  applyCompletion: (lines, cursorLine, _col, item, prefix) => ({ lines: [`/${item.value} `, ...lines.slice(1)], cursorLine, cursorCol: prefix.length }),
+};
+const aliases = new Map([
+  ['poteto-mode', "poteto's agent style"],
+  ['poteto-help', 'Guides users through pstack'],
+  ['how', 'Explains how code works'],
+]);
+const signal = new AbortController().signal;
+
+describe('alias autocomplete (CMD-003)', () => {
+  test('lists matching pstack skills under their Cursor names ahead of the built-in suggestions', async () => {
+    const provider = aliasAutocomplete(current, aliases);
+    expect(await provider.getSuggestions(['/pot'], 0, 4, { signal })).toEqual({
+      prefix: '/pot',
+      items: [{ value: 'poteto-mode', label: 'poteto-mode', description: "poteto's agent style" }, { value: 'poteto-help', label: 'poteto-help', description: 'Guides users through pstack' }, ...builtin],
+    });
+  });
+
+  test('leaves completions alone outside a leading command token', async () => {
+    const provider = aliasAutocomplete(current, aliases);
+    expect(await provider.getSuggestions(['/how why'], 0, 8, { signal })).toEqual({ items: builtin, prefix: '/how why' });
+    expect(await provider.getSuggestions(['say /pot'], 0, 8, { signal })).toEqual(null);
+  });
+
+  test('applies an alias like any command completion', () => {
+    const provider = aliasAutocomplete(current, aliases);
+    expect(provider.applyCompletion(['/pot'], 0, 4, { value: 'poteto-mode', label: 'poteto-mode' }, '/pot')).toEqual({ lines: ['/poteto-mode '], cursorLine: 0, cursorCol: 4 });
+  });
+});

package/test/e2e/aliases.e2e.test.ts

@@ -0,0 +1,81 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { PACKAGE_ROOT } from '../../src/paths.ts';
+import { assistantTexts, contentText, makeSandbox, messages, piInvocation, runJson, type Sandbox } from './harness.ts';
+
+let sandbox: Sandbox;
+beforeEach(() => {
+  sandbox = makeSandbox();
+});
+afterEach(() => sandbox.dispose());
+
+test('/how attaches the skill body, path, and raw arguments to one message (CMD-001)', async () => {
+  const run = await runJson(sandbox, '/how why "quoted" $1 stays\n@@say ALIAS-OK', ['--no-session']);
+  const [user] = messages(run.events, 'user').map((message) => contentText(message.content));
+  const skillFile = join(PACKAGE_ROOT, 'skills/how/SKILL.md');
+  expect(user).toContain(`<skill name="how" location="${skillFile}">`);
+  expect(user).toContain(`References are relative to ${join(PACKAGE_ROOT, 'skills/how')}.`);
+  expect(user).toContain('# How\n\nExplore the codebase');
+  expect(user?.endsWith('</skill>\n\nwhy "quoted" $1 stays\n@@say ALIAS-OK')).toBe(true);
+  expect(assistantTexts(run.events)).toEqual(['ALIAS-OK']);
+});
+
+test('the skill does not ride along on the next message (CMD-001)', async () => {
+  const run = await runJson(sandbox, ['/ketchup @@say FIRST', 'next turn\n@@say SECOND'], ['--no-session']);
+  const users = messages(run.events, 'user').map((message) => contentText(message.content));
+  expect(users).toHaveLength(2);
+  expect(users[0]).toContain('<skill name="ketchup"');
+  expect(users[1]).toBe('next turn\n@@say SECOND');
+  expect(assistantTexts(run.events)).toEqual(['FIRST', 'SECOND']);
+});
+
+test('aliases work in print mode, where extension commands cannot start a run (CMD-001)', () => {
+  const result = spawnSync(...piInvocation(['-p', '--offline', '--no-session', '--model', 'scripted/echo', '/principle-prove-it-works @@say PRINT-OK']), {
+    cwd: sandbox.workDir,
+    env: sandbox.env,
+    encoding: 'utf8',
+    timeout: 45_000,
+  });
+  expect(result.stdout.trim()).toBe('PRINT-OK');
+  expect(result.status).toBe(0);
+});
+
+test("a user's own prompt template of the same name wins over the alias (CMD-002)", async () => {
+  mkdirSync(join(sandbox.agentDir, 'prompts'));
+  writeFileSync(join(sandbox.agentDir, 'prompts/how.md'), '---\ndescription: my how\n---\nMY-TEMPLATE $@\n');
+  const run = await runJson(sandbox, '/how hello', ['--no-session']);
+  expect(assistantTexts(run.events)).toEqual(['ECHO: MY-TEMPLATE hello']);
+});
+
+test('aliases work when the package is installed through a symlink (recheck 1)', async () => {
+  const link = join(sandbox.root, 'pkglink');
+  symlinkSync(PACKAGE_ROOT, link);
+  writeFileSync(join(sandbox.agentDir, 'settings.json'), JSON.stringify({ packages: [link], extensions: [join(PACKAGE_ROOT, 'test/fixtures/scripted-model.ts')] }));
+  const run = await runJson(sandbox, '/ketchup now\n@@say LINKED', ['--no-session']);
+  const [user] = messages(run.events, 'user').map((message) => contentText(message.content));
+  expect([user?.startsWith('<skill name="ketchup"'), assistantTexts(run.events)]).toEqual([true, ['LINKED']]);
+});
+
+test("a skill of the user's own gets a /name alias too, as in Cursor (review r2: parity 1)", async () => {
+  mkdirSync(join(sandbox.agentDir, 'skills/jay-mode'), { recursive: true });
+  writeFileSync(join(sandbox.agentDir, 'skills/jay-mode/SKILL.md'), '---\nname: jay-mode\ndescription: Work in Jay style.\ndisable-model-invocation: true\n---\nJAY BODY\n');
+  const run = await runJson(sandbox, '/jay-mode hello\n@@say JAY', ['--no-session']);
+  const [user] = messages(run.events, 'user').map((message) => contentText(message.content));
+  expect([user?.startsWith('<skill name="jay-mode"'), assistantTexts(run.events)]).toEqual([true, ['JAY']]);
+});
+
+test('aliases work when skill commands are hidden from the / menu', async () => {
+  const settings = JSON.parse(readFileSync(join(sandbox.agentDir, 'settings.json'), 'utf8')) as Record<string, unknown>;
+  writeFileSync(join(sandbox.agentDir, 'settings.json'), JSON.stringify({ ...settings, enableSkillCommands: false }));
+  const run = await runJson(sandbox, '/how now\n@@say HIDDEN', ['--no-session']);
+  const [user] = messages(run.events, 'user').map((message) => contentText(message.content));
+  expect([user?.startsWith('<skill name="how"'), assistantTexts(run.events)]).toEqual([true, ['HIDDEN']]);
+});
+
+test('non-alias slash text reaches the model unchanged (CMD-002)', async () => {
+  const run = await runJson(sandbox, '/howdy partner', ['--no-session']);
+  expect(assistantTexts(run.events)).toEqual(['ECHO: /howdy partner']);
+});