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

package/src/loop.ts

@@ -0,0 +1,238 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { isOneShot } from './modes.ts';
+
+const DAY_MS = 86_400_000;
+const UNIT_MS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: DAY_MS };
+const DURATION = /^(?:\d+[smhd])+$/;
+const WORD_UNITS: Record<string, string> = { second: 's', seconds: 's', sec: 's', secs: 's', minute: 'm', minutes: 'm', min: 'm', mins: 'm', hour: 'h', hours: 'h', hr: 'h', hrs: 'h', day: 'd', days: 'd' };
+// setTimeout fires at once for delays past 2^31-1 ms (about 24.8 days), which would turn a long loop into a runaway.
+const MAX_DELAY_MS = 24 * DAY_MS;
+const TOO_LONG = 'Loop intervals can be at most 24d.';
+
+/** Milliseconds for a duration such as 30s, 5m, 1h30m, 10 minutes, or 1 hour 30 minutes; undefined when the text is not a duration. */
+export function parseDuration(text: string): number | undefined {
+  const compact = text
+    .trim()
+    .toLowerCase()
+    .replace(/^every\s+/, '')
+    .replace(/(\d+)\s*(seconds?|secs?|minutes?|mins?|hours?|hrs?|days?)\b/g, (_match, count: string, word: string) => `${count}${WORD_UNITS[word] ?? ''}`)
+    .replace(/\s+/g, '');
+  if (!DURATION.test(compact)) return undefined;
+  const total = [...compact.matchAll(/(\d+)([smhd])/g)].reduce((sum, [, count, unit]) => sum + Number(count) * (UNIT_MS[unit ?? 's'] ?? 0), 0);
+  return total > 0 ? total : undefined;
+}
+
+function delayOf(text: string): number {
+  const ms = parseDuration(text);
+  if (ms === undefined) throw new Error(`"${text}" is not a duration such as 30s, 10m, or 1h.`);
+  if (ms > MAX_DELAY_MS) throw new Error(TOO_LONG);
+  return ms;
+}
+
+export type LoopCommand = { kind: 'status' } | { kind: 'stop' } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
+
+/** The longest trailing phrase that parses as a duration, such as `5m`, `every 10 minutes`, or `1 hour 30 minutes`. */
+function trailingInterval(text: string): { prompt: string; intervalMs: number } | undefined {
+  const tokens = text.split(/\s+/);
+  for (let take = Math.min(6, tokens.length); take >= 1; take -= 1) {
+    const intervalMs = parseDuration(tokens.slice(-take).join(' '));
+    if (intervalMs === undefined) continue;
+    const prompt = tokens
+      .slice(0, -take)
+      .join(' ')
+      .replace(/\s+every$/i, '')
+      .trim();
+    return { prompt, intervalMs };
+  }
+  return undefined;
+}
+
+export function parseLoopArgs(args: string): LoopCommand {
+  const trimmed = args.trim();
+  if (trimmed === '') return { kind: 'status' };
+  if (trimmed === 'stop' || trimmed === 'off') return { kind: 'stop' };
+  const [, first = '', rest = ''] = /^(\S+)\s*([\s\S]*)$/.exec(trimmed) ?? [];
+  const leadMs = parseDuration(first) ?? (first.toLowerCase() === 'every' ? parseDuration(rest.split(/\s+/)[0] ?? '') : undefined);
+  if (leadMs !== undefined) {
+    if (leadMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    const after = first.toLowerCase() === 'every' ? rest.split(/\s+/).slice(1).join(' ') : rest;
+    return after.trim() === '' ? { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' } : { kind: 'start', prompt: after.trim(), intervalMs: leadMs };
+  }
+  // Cursor accepts the interval at either end, including `every 10 minutes`, so both ends are tried before treating it as a prompt.
+  const trailing = trailingInterval(trimmed);
+  if (trailing !== undefined) {
+    if (trailing.intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    if (trailing.prompt === '') return { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' };
+    return { kind: 'start', prompt: trailing.prompt, intervalMs: trailing.intervalMs };
+  }
+  return { kind: 'start', prompt: trimmed };
+}
+
+interface Loop {
+  prompt: string;
+  intervalMs?: number;
+  iteration: number;
+  nextWakeMs?: number;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+const formatMs = (ms: number) => (ms % 86_400_000 === 0 ? `${ms / 86_400_000}d` : ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1_000)}s`);
+
+/** Loop state rides in the system prompt, so the prompt itself stays verbatim and a template prompt keeps it too. */
+function loopSection(loop: Loop): string {
+  if (loop.intervalMs !== undefined) {
+    return `A /loop is running: iteration ${loop.iteration}, every ${formatMs(loop.intervalMs)}. The user ends it with /loop stop; call the Loop tool with stop: true once the goal is met.`;
+  }
+  return `A /loop is running: iteration ${loop.iteration}, agent-paced. Call the Loop tool with wake_in (like 10m) to schedule the next run, or stop: true to end it. Without a wake_in call the loop ends after this turn.`;
+}
+
+export interface LoopOptions {
+  /** True while this session waits on work that will wake the agent, such as background subagents. */
+  hasPendingWork: () => boolean;
+}
+
+function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
+  let loop: Loop | undefined;
+  let lastCtx: ExtensionContext | undefined;
+
+  const notify = (ctx: ExtensionContext | undefined, message: string) => {
+    if (ctx?.hasUI) ctx.ui.notify(message, 'info');
+  };
+  const clear = () => {
+    if (loop?.timer !== undefined) clearTimeout(loop.timer);
+    loop = undefined;
+  };
+  const stop = (ctx: ExtensionContext | undefined, reason: string) => {
+    clear();
+    notify(ctx, `Loop stopped: ${reason}`);
+  };
+  const fire = (first = false) => {
+    if (loop === undefined) return;
+    // A scheduled tick that lands mid-run is skipped rather than queued, so one long run cannot leave a pile of stale ticks.
+    if (!first && lastCtx !== undefined && !lastCtx.isIdle()) {
+      if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+      return;
+    }
+    const { timer: _timer, nextWakeMs: _wake, ...rest } = loop;
+    loop = { ...rest, iteration: rest.iteration + 1 };
+    // Expansion lets a loop run a skill or template each time.
+    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true });
+    // A fixed loop is wall-clock from each fire, like the reference's sleep loop: a long run does not push the next tick out.
+    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+  };
+  const settled = (ctx: ExtensionContext, aborted: boolean) => {
+    lastCtx = ctx;
+    if (loop === undefined) return;
+    if (aborted) return stop(ctx, 'the run was aborted.');
+    if (loop.timer !== undefined) return;
+    if (loop.intervalMs !== undefined) {
+      // An armed fixed loop has no timer yet; its first tick waits for this turn to end.
+      loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+      return;
+    }
+    const delay = loop.nextWakeMs;
+    if (delay !== undefined) loop = { ...loop, timer: setTimeout(fire, delay) };
+    else if (!options.hasPendingWork()) stop(ctx, 'the agent scheduled no next wake.');
+  };
+  const start = (ctx: ExtensionContext, prompt: string, intervalMs: number | undefined) => {
+    if (loop !== undefined) stop(ctx, 'replaced by a new /loop.');
+    lastCtx = ctx;
+    loop = { prompt, iteration: 0, ...(intervalMs === undefined ? {} : { intervalMs }) };
+    fire(true);
+  };
+  /** An agent arms a loop mid-turn, so its first run waits for this turn to settle and then for the first delay. */
+  const arm = (ctx: ExtensionContext, prompt: string, schedule: { intervalMs: number } | { firstWakeMs: number }) => {
+    if (loop !== undefined) stop(ctx, 'replaced by a new loop.');
+    loop = 'intervalMs' in schedule ? { prompt, iteration: 0, intervalMs: schedule.intervalMs } : { prompt, iteration: 0, nextWakeMs: schedule.firstWakeMs };
+  };
+  const status = () =>
+    loop === undefined
+      ? 'No loop is running. Usage: /loop [interval] <prompt>, with the interval at either end; /loop stop ends one.'
+      : `Loop: "${loop.prompt}" (iteration ${loop.iteration}${loop.intervalMs === undefined ? ', agent-paced' : `, every ${formatMs(loop.intervalMs)}`})`;
+  const wake = (delayMs: number) => {
+    if (loop === undefined) throw new Error('No loop is running. Start one with prompt plus interval or wake_in, or ask the user to run /loop.');
+    if (loop.intervalMs !== undefined) throw new Error(`This loop runs every ${formatMs(loop.intervalMs)}; only the user can change its interval. Pass stop: true to end it.`);
+    // A wake already scheduled is replaced, so the new delay counts from the end of this turn.
+    if (loop.timer !== undefined) clearTimeout(loop.timer);
+    const { timer: _timer, ...rest } = loop;
+    loop = { ...rest, nextWakeMs: delayMs };
+  };
+  const section = () => (loop === undefined ? undefined : loopSection(loop));
+  return { notify, stop, settled, start, arm, status, wake, clear, section, active: () => loop !== undefined };
+}
+
+type LoopController = ReturnType<typeof createLoopController>;
+
+const ONE_SHOT = '/loop needs an interactive or RPC session; print and JSON runs exit when the agent settles.';
+
+function handleLoopCommand(controller: LoopController, args: string, ctx: ExtensionCommandContext): void {
+  const command = parseLoopArgs(args);
+  if (command.kind === 'status') controller.notify(ctx, controller.status());
+  else if (command.kind === 'stop') controller.stop(ctx, 'stopped by /loop stop.');
+  else if (command.kind === 'error') controller.notify(ctx, command.message);
+  else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
+  else controller.start(ctx, command.prompt, command.intervalMs);
+}
+
+const LoopParams = Type.Object({
+  prompt: Type.Optional(Type.String({ description: 'Start (or replace) a loop that sends this prompt each run. It may be a skill or template command such as /poteto-mode <task>.' })),
+  interval: Type.Optional(Type.String({ description: 'With prompt: a fixed cadence such as 30m or 1h; the first run starts that long after this turn ends.' })),
+  wake_in: Type.Optional(Type.String({ description: 'With prompt: the first run of an agent-paced loop. Alone: the next run of the running agent-paced loop. A duration such as 10m, at most 24d.' })),
+  stop: Type.Optional(Type.Boolean({ description: 'End the loop once its goal is met.' })),
+});
+
+function loopToolText(controller: LoopController, params: { prompt?: string; interval?: string; wake_in?: string; stop?: boolean }, ctx: ExtensionContext): string {
+  if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+  if (params.stop === true) {
+    if (!controller.active()) throw new Error('No loop is running.');
+    controller.stop(ctx, 'the agent ended it.');
+    return 'Loop stopped.';
+  }
+  if (params.prompt !== undefined) {
+    if (params.interval !== undefined) {
+      const intervalMs = delayOf(params.interval);
+      controller.arm(ctx, params.prompt, { intervalMs });
+      return `Loop armed: "${params.prompt}" every ${formatMs(intervalMs)}; the first run starts ${formatMs(intervalMs)} after this turn ends.`;
+    }
+    if (params.wake_in === undefined) throw new Error('To start a loop, pass interval for a fixed cadence or wake_in for the first run of an agent-paced loop.');
+    const firstWakeMs = delayOf(params.wake_in);
+    controller.arm(ctx, params.prompt, { firstWakeMs });
+    return `Loop armed: "${params.prompt}", agent-paced; the first run starts ${formatMs(firstWakeMs)} after this turn ends.`;
+  }
+  if (params.interval !== undefined) throw new Error('interval applies only when starting a loop with prompt.');
+  if (params.wake_in === undefined) throw new Error('Pass prompt with interval or wake_in to start a loop, wake_in to schedule the next run, or stop: true.');
+  const delay = delayOf(params.wake_in);
+  controller.wake(delay);
+  return `Next loop run in ${formatMs(delay)}, after this turn ends.`;
+}
+
+function registerLoopTool(pi: ExtensionAPI, controller: LoopController): void {
+  pi.registerTool({
+    name: 'Loop',
+    label: 'Loop',
+    description: '/loop for you: start a loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule the next wake of an agent-paced loop, or stop the loop once its goal is met. Use it when a playbook says to arm /loop.',
+    promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
+    parameters: LoopParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return { content: [{ type: 'text', text: loopToolText(controller, params, ctx) }], details: undefined };
+    },
+  });
+}
+
+/** /loop: run a prompt at a fixed interval, or at wakes the agent picks, until stopped. */
+export function registerLoop(pi: ExtensionAPI, options: LoopOptions): { section: () => string | undefined } {
+  const controller = createLoopController(pi, options);
+  pi.on('session_start', (_event, ctx) => {
+    if (isOneShot(ctx.mode)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== 'Loop'));
+  });
+  pi.on('agent_settled', (event, ctx) => controller.settled(ctx, event.aborted));
+  pi.on('session_shutdown', () => controller.clear());
+  pi.registerCommand('loop', {
+    description: 'Run a prompt repeatedly: /loop [interval] <prompt>, interval either end and like 30s, 5m, 1h, every 10 minutes (at most 24d); /loop stop',
+    handler: async (args, ctx) => handleLoopCommand(controller, args, ctx),
+  });
+  registerLoopTool(pi, controller);
+  return { section: controller.section };
+}

package/src/mode.ts

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ThemeColor } from '@earendil-works/pi-coding-agent';
+import { parseFrontmatter, stripFrontmatter } from '@earendil-works/pi-coding-agent';
+
+export const MODE_ENTRY = 'pstack/mode';
+const STATUS_KEY = 'pstack-mode';
+
+/** The mode on the branch. `path` is the loaded skill's file; absent when no loaded skill has the name. */
+export interface ActiveMode {
+  skill: string;
+  path?: string;
+}
+
+export type ModeCommand = { kind: 'status' } | { kind: 'off' } | { kind: 'set'; skill: string; task: string };
+
+export function parseModeArgs(args: string): ModeCommand {
+  const trimmed = args.trim();
+  if (trimmed === '') return { kind: 'status' };
+  if (trimmed === 'off') return { kind: 'off' };
+  const match = /^\/?(\S+)(?:\s([\s\S]*))?$/.exec(trimmed);
+  return { kind: 'set', skill: match?.[1] ?? trimmed, task: (match?.[2] ?? '').trim() };
+}
+
+interface BranchEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+/**
+ * The last mode entry on the branch, as a skill name only: a session file can come from elsewhere, so a stored path
+ * is ignored and a value that is not a plausible skill name (it would reach the system prompt) counts as no mode.
+ */
+export function modeFromBranch(entries: readonly BranchEntry[]): ActiveMode | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== 'custom' || entry.customType !== MODE_ENTRY) continue;
+    const skill = (entry.data as { skill?: unknown } | null)?.skill;
+    return typeof skill === 'string' && SKILL_NAME.test(skill) ? { skill } : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * The mode text for a request. Cursor attaches the skill once, on the turn that enters the mode, then sends a reminder
+ * that names the skill path each turn. Pi rebuilds its prompt per request, so the body rides the first request after
+ * entry and a reminder follows. A mode whose body was never sent re-sends it, so a restart cannot leave a mode
+ * unread.
+ */
+export function modeSection(mode: ActiveMode, includeBody: boolean): string {
+  if (mode.path === undefined) return `Mode ${mode.skill} is on, but no loaded skill has that name. Tell the user to run /mode off or /mode <skill>.`;
+  if (!existsSync(mode.path)) return `Mode ${mode.skill} is on, but its skill file ${mode.path} no longer exists. Tell the user to run /mode off or /mode <skill>.`;
+  if (!includeBody)
+    return `Reminder: you are still in ${mode.skill} mode. Follow that mode's skill on this turn. Do not drop it because the request looks small or you already have context. Do not drift back to default agent behavior. If you cannot state the mode's hard rules, read ${JSON.stringify(mode.path)} before acting.`;
+  // The frontmatter, including `reminder`, stays out of the model's context in a mode (MODE-004).
+  const body = stripFrontmatter(readFileSync(mode.path, 'utf8')).trim();
+  return [
+    `The user has entered ${mode.skill} custom mode. Follow the skill instructions in ${JSON.stringify(mode.path)} until the user exits or switches modes. Do not drift back to default agent behavior.`,
+    `<skill name="${mode.skill}" location="${mode.path}">`,
+    `References are relative to ${dirname(mode.path)}.`,
+    '',
+    body,
+    '</skill>',
+  ].join('\n');
+}
+
+// A mode's badge shows the skill's `icon` (default: lightning) and `color`. Icon names map to terminal glyphs and
+// color names to the nearest theme color.
+const BADGE_ICONS: Record<string, string> = {
+  crown: '♛',
+  lightning: '⚡',
+  code: '</>',
+  terminal: '>_',
+  bug: '✱',
+  'git-branch': '⎇',
+  'book-open': '❐',
+  beaker: '⚗',
+  shield: '⛨',
+  rocket: '➶',
+};
+const BADGE_COLORS: Record<string, ThemeColor> = { green: 'success', red: 'error', yellow: 'warning', orange: 'warning', cyan: 'accent', blue: 'accent', purple: 'accent', magenta: 'accent', brand: 'accent' };
+
+/** A skill carries `icon` and `color` under `metadata`, or at the top level of its frontmatter. */
+function skillMetadata(mode: ActiveMode): Record<string, unknown> {
+  if (mode.path === undefined || !existsSync(mode.path)) return {};
+  const { frontmatter } = parseFrontmatter(readFileSync(mode.path, 'utf8'));
+  const metadata = typeof frontmatter['metadata'] === 'object' && frontmatter['metadata'] !== null ? (frontmatter['metadata'] as Record<string, unknown>) : {};
+  return { icon: frontmatter['icon'], color: frontmatter['color'], ...metadata };
+}
+
+export function modeBadge(mode: ActiveMode, metadata: Record<string, unknown> = skillMetadata(mode)): { text: string; color?: ThemeColor } {
+  const iconName = String(metadata['icon']);
+  const colorName = String(metadata['color']);
+  const icon = Object.hasOwn(BADGE_ICONS, iconName) ? BADGE_ICONS[iconName] : BADGE_ICONS['lightning'];
+  const color = Object.hasOwn(BADGE_COLORS, colorName) ? BADGE_COLORS[colorName] : undefined;
+  return { text: `${icon} mode: ${mode.skill}`, ...(color === undefined ? {} : { color }) };
+}
+
+function loadedSkills(pi: ExtensionAPI): Map<string, string> {
+  const skills = new Map<string, string>();
+  for (const command of pi.getCommands()) {
+    if (command.source === 'skill' && command.name.startsWith('skill:')) skills.set(command.name.slice('skill:'.length), command.sourceInfo.path);
+  }
+  return skills;
+}
+
+export function registerMode(pi: ExtensionAPI): { section: () => string | undefined } {
+  let active: ActiveMode | undefined;
+  // The mode whose body the conversation already carries; cleared on entry, exit, and session change.
+  let bodySent: string | undefined;
+  const show = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    const badge = active === undefined ? undefined : modeBadge(active);
+    ctx.ui.setStatus(STATUS_KEY, badge === undefined ? undefined : badge.color === undefined ? badge.text : ctx.ui.theme.fg(badge.color, badge.text));
+  };
+  // The skill is looked up by name among loaded skills; a stored path is never read, since it can be stale or crafted.
+  const restore = (ctx: ExtensionContext) => {
+    const stored = modeFromBranch(ctx.sessionManager.getBranch());
+    active = stored === undefined ? undefined : (tryResolve(stored.skill) ?? { skill: stored.skill });
+    bodySent = undefined;
+    show(ctx);
+  };
+  pi.on('session_start', (_event, ctx) => restore(ctx));
+  pi.on('session_tree', (_event, ctx) => restore(ctx));
+
+  const resolveSkill = (name: string): ActiveMode => {
+    const skills = loadedSkills(pi);
+    const path = skills.get(name);
+    if (path === undefined) throw new Error(`No skill named "${name}". Skills that can back a mode: ${[...skills.keys()].toSorted().join(', ')}.`);
+    return { skill: name, path };
+  };
+
+  function tryResolve(name: string): ActiveMode | undefined {
+    try {
+      return resolveSkill(name);
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('No skill named')) return undefined;
+      throw error;
+    }
+  }
+
+  const handle = (args: string, ctx: ExtensionCommandContext) => {
+    const command = parseModeArgs(args);
+    if (command.kind === 'status') return ctx.ui.notify(active === undefined ? 'No mode is on.' : `Mode on: ${active.skill} (${active.path ?? 'no loaded skill has that name'}).`, 'info');
+    active = command.kind === 'off' ? undefined : resolveSkill(command.skill);
+    bodySent = undefined;
+    pi.appendEntry(MODE_ENTRY, active === undefined ? null : { skill: active.skill });
+    show(ctx);
+    ctx.ui.notify(active === undefined ? 'Mode off.' : `Mode on: ${active.skill}. /mode off exits.`, 'info');
+    if (command.kind === 'set' && command.task !== '') pi.sendUserMessage(command.task, { expandPromptTemplates: true, ...(ctx.isIdle() ? {} : { deliverAs: 'followUp' as const }) });
+    return undefined;
+  };
+
+  pi.registerCommand('mode', {
+    description: 'Keep a skill on every turn: /mode <skill> [task], /mode off, /mode',
+    getArgumentCompletions: (prefix) => ['off', ...[...loadedSkills(pi).keys()].toSorted()].filter((name) => name.startsWith(prefix.trim())).map((name) => ({ value: name, label: name })),
+    handler: async (args, ctx) => {
+      try {
+        handle(args, ctx);
+      } catch (error) {
+        ctx.ui.notify((error as Error).message, 'error');
+      }
+    },
+  });
+
+  return {
+    section: () => {
+      if (active === undefined) return undefined;
+      const includeBody = bodySent !== active.skill;
+      // Only a request that actually carried the body counts as sent, so a missing skill file cannot silence the body
+      // after the file comes back.
+      if (includeBody && active.path !== undefined && existsSync(active.path)) bodySent = active.skill;
+      return modeSection(active, includeBody);
+    },
+  };
+}

package/src/modes.ts

@@ -0,0 +1,8 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { childIdentity } from './child-env.ts';
+
+/** Print and JSON runs exit once the agent settles, and so does every subagent, an RPC child that its owner closes then. */
+export const isOneShot = (mode: ExtensionContext['mode']): boolean => mode === 'print' || mode === 'json' || childIdentity.depth > 0;
+
+/** Whether a user can answer a dialog. A subagent's owner dismisses every dialog, so a subagent has nobody to ask. */
+export const canAsk = (ctx: Pick<ExtensionContext, 'hasUI'>): boolean => ctx.hasUI && childIdentity.depth === 0;

package/src/path-skills.ts

@@ -0,0 +1,104 @@
+// 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);
+    },
+  };
+}

package/src/paths.ts

@@ -0,0 +1,90 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { childIdentity } from './child-env.ts';
+
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const SKILLS_DIR = join(PACKAGE_ROOT, 'skills');
+export const AGENTS_DIR = join(PACKAGE_ROOT, 'agents');
+
+/** Pi-owned state for this package. Follows PI_CODING_AGENT_DIR, so tests and users can relocate it. */
+export function stateDir(): string {
+  return join(getAgentDir(), 'pstack');
+}
+
+/** The model rule: pstack's per-role model choices, added to every request's system prompt. */
+export function rulePath(): string {
+  return join(stateDir(), 'pstack-models.md');
+}
+
+/** Webhook routines' sender keys, one `<slug>/credentials.json` each. */
+export function routinesDir(): string {
+  return join(stateDir(), 'routines');
+}
+
+/** Plan-mode artifacts, the way Cursor keeps a plan file under `~/.cursor/plans`. */
+export function plansDir(): string {
+  return join(stateDir(), 'plans');
+}
+
+/** Desired-state registry and supervisor runtime for one workspace. */
+export function durableDir(cwd: string): string {
+  return join(stateDir(), 'durable', workspaceSlug(cwd));
+}
+
+export function durableRegistryPath(cwd: string): string {
+  return join(durableDir(cwd), 'subscriptions.json');
+}
+
+export function durableRuntimeDir(cwd: string): string {
+  return join(durableDir(cwd), 'runtime');
+}
+
+/**
+ * Pi's rule for a session folder name, so per-workspace state lines up with `<agentDir>/sessions/<slug>`. The live
+ * `sessionManager.getSessionDir()` needs a session and names the current one, which is `<workspace>/subagents` in a
+ * subagent, so the rule stays here for a working directory (docs/native-gaps.md).
+ */
+export function workspaceSlug(cwd: string): string {
+  return `--${resolve(cwd)
+    .replace(/^[/\\]/, '')
+    .replace(/[/\\:]/g, '-')}--`;
+}
+
+/**
+ * State for one working directory, so transcripts and stores never cross workspaces (pstack's own rule). A subagent
+ * uses its main chat's, so an isolated worker in its own worktree shares the tree's Projects, records, and transcripts.
+ */
+export function workspaceStateDir(cwd: string, inherited: string | undefined = childIdentity.workspaceState): string {
+  return inherited ?? join(stateDir(), 'workspaces', workspaceSlug(cwd));
+}
+
+/** Subagent transcripts, records, and run locks for this workspace. */
+export function subagentDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'subagents');
+}
+
+/** Projects of this workspace: `<slug>/notes.md` is a project's tracker and `<slug>/store/` its store. */
+export function projectsDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'projects');
+}
+
+/** Files a session's tools produce for the user, such as visualize's SVG charts. */
+export function artifactsDir(cwd: string, sessionId: string): string {
+  return join(workspaceStateDir(cwd), 'artifacts', sessionId);
+}
+
+export function worktreesDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'worktrees');
+}
+
+/** The store of the main chat that started this subagent tree, which autopilot owners write their trails into. */
+export function rootStoreDir(cwd: string, sessionId: string, inherited: string | undefined): string {
+  return inherited ?? storeDir(cwd, sessionId);
+}
+
+/** "The current agent's store" that orchestrate's store layout writes into: one directory per session. */
+export function storeDir(cwd: string, sessionId: string): string {
+  return join(workspaceStateDir(cwd), 'store', sessionId);
+}

package/src/pi-command.ts

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import { basename } from 'node:path';
+
+/**
+ * Argv prefix for spawning Pi: the running script when available so children match
+ * the parent's Pi version, else `pi` on PATH. Same rule as task/tool.ts historically.
+ */
+export function piCommand(): string[] {
+  const script = process.argv[1];
+  if (script !== undefined && !script.startsWith('/$bunfs/') && existsSync(script)) return [process.execPath, script];
+  return /^(node|bun)(\.exe)?$/.test(basename(process.execPath).toLowerCase()) ? ['pi'] : [process.execPath];
+}