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

package/skills/why/references/sources/sentry.md

@@ -0,0 +1,66 @@
+# Sentry Error History
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?).
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/skills/why/references/sources/slack.md

@@ -0,0 +1,17 @@
+# Slack Conversations
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,129 @@
+# Synthesizer Prompt Template
+
+Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
+
+1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Document gaps. Don't fill them with plausible-sounding guesses.
+6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
+
+## Instructions
+
+1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
+2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
+3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
+4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
+5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
+6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
+
+## Output Format
+
+Write for the user, in this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
+
+### What We Found
+
+Claims with textual evidence, each quoted or paraphrased and cited precisely:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
+
+### What We Can Reasonably Infer
+
+Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+Skip this section if there's nothing to infer.
+
+### Competing Hypotheses
+
+If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
+
+- Questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
+- People who would likely know but whom you can't ask
+
+### Sources Consulted
+
+What was actually searched, so the user can judge coverage and redirect:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences on overall confidence, e.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Revise if any item fails:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface every contradiction you noticed, or quietly pick one?
+4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
+6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
+7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
+
+The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.

package/src/aliases.ts

@@ -0,0 +1,64 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+
+import type { ImageContent } from '@earendil-works/pi-ai';
+import type { SlashCommandInfo } from '@earendil-works/pi-coding-agent';
+import { SKILLS_DIR } from './paths.ts';
+
+const ALIAS = /^\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/;
+const SKILL_PREFIX = 'skill:';
+
+const isSkill = (command: SlashCommandInfo) => command.source === 'skill' && command.name.startsWith(SKILL_PREFIX);
+
+/**
+ * `/name` aliases with their descriptions: every skill Pi loaded, so any skill attaches by name
+ * (pstack itself creates skills such as `/<handle>-mode`), minus any name a prompt template or extension command owns.
+ * Settings that filter a skill out also drop its alias. Pi handles its built-in commands before the input event.
+ */
+export function aliasTable(commands: readonly SlashCommandInfo[]): ReadonlyMap<string, string> {
+  const taken = new Set(commands.filter((command) => command.source !== 'skill').map((command) => command.name));
+  const table = new Map<string, string>();
+  for (const command of commands.filter(isSkill)) {
+    const name = command.name.slice(SKILL_PREFIX.length);
+    if (!taken.has(name)) table.set(name, command.description ?? '');
+  }
+  return table;
+}
+
+// Pi records a skill path as configured, which can run through a symlink; realpaths are cached per runtime.
+const realPaths = new Map<string, string | undefined>();
+function realPath(path: string): string | undefined {
+  if (!realPaths.has(path)) realPaths.set(path, existsSync(path) ? realpathSync(path) : undefined);
+  return realPaths.get(path);
+}
+
+/** Names of the loaded skills that live in this package, sorted; the host map's skill list. */
+export function packageSkillNames(commands: readonly SlashCommandInfo[], skillsDir: string = SKILLS_DIR): string[] {
+  const root = `${realPath(skillsDir) ?? skillsDir}${sep}`;
+  return commands
+    .filter((command) => isSkill(command) && realPath(command.sourceInfo.path)?.startsWith(root) === true)
+    .map((command) => command.name.slice(SKILL_PREFIX.length))
+    .toSorted();
+}
+
+/**
+ * Rewrites `/name args` to Pi's native `/skill:name args` for an aliased skill, keeping the argument text.
+ * Pi splits the skill name at the first space and trims the arguments, so a space always follows the name.
+ */
+export function aliasTransform(text: string, names: ReadonlySet<string>): string | undefined {
+  const match = ALIAS.exec(text);
+  const name = match?.[1];
+  if (match === null || name === undefined || !names.has(name)) return undefined;
+  const rest = text.slice(match[0].length);
+  if (rest.length === 0) return `/skill:${name}`;
+  return `/skill:${name} ${rest.startsWith(' ') ? rest.slice(1) : rest}`;
+}
+
+export type AliasInputResult = { action: 'continue' } | { action: 'transform'; text: string; images?: ImageContent[] };
+
+/** The `input` handler result: Pi's native skill command for an aliased skill, otherwise continue unchanged. */
+export function aliasInputResult(event: { text: string; images?: ImageContent[] }, names: ReadonlySet<string>): AliasInputResult {
+  const text = aliasTransform(event.text, names);
+  if (text === undefined) return { action: 'continue' };
+  return { action: 'transform', text, ...(event.images === undefined ? {} : { images: event.images }) };
+}

package/src/ask.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { canAsk } from './modes.ts';
+
+export const DONE_LABEL = '✓ Done selecting';
+// Every question ends with a typed-answer option.
+export const OTHER_LABEL = 'Other: (type to answer)';
+export const OTHER_ID = 'other';
+const SKIPPED = 'skipped (no one can answer questions in this session; decide yourself and say what you chose)';
+
+export const AskParams = Type.Object({
+  title: Type.Optional(Type.String({ description: 'Short heading shown above the questions' })),
+  questions: Type.Array(
+    Type.Object({
+      id: Type.String({ description: 'Stable identifier for the question' }),
+      prompt: Type.String({ description: 'The question shown to the user' }),
+      options: Type.Array(Type.Object({ id: Type.String(), label: Type.String(), description: Type.Optional(Type.String({ description: 'Detail shown after the label' })) }), {
+        description: 'Choices the user picks from',
+      }),
+      allow_multiple: Type.Optional(Type.Boolean({ description: 'Let the user pick several options' })),
+    }),
+    { description: 'Questions asked one after another' },
+  ),
+});
+export type Question = Static<typeof AskParams>['questions'][number];
+type Option = Question['options'][number];
+
+/** What the user sees for an option: its label, then its description when it has one. */
+const shown = (option: Option): string => (option.description === undefined || option.description === '' ? option.label : `${option.label} — ${option.description}`);
+
+function duplicate(values: readonly string[]): string | undefined {
+  return values.find((value, index) => values.indexOf(value) !== index);
+}
+
+/** Answers map back to options by their shown text, so that text and ids must be unique, and the sentinels are reserved. */
+export function validateQuestions(questions: readonly Question[]): void {
+  const repeatedId = duplicate(questions.map((question) => question.id));
+  if (repeatedId !== undefined) throw new Error(`Question id "${repeatedId}" appears more than once.`);
+  for (const question of questions) {
+    if (question.options.length === 0) throw new Error(`Question "${question.id}" has no options.`);
+    const label = duplicate(question.options.map(shown));
+    if (label !== undefined) throw new Error(`Question "${question.id}" has two options labelled "${label}".`);
+    const id = duplicate(question.options.map((option) => option.id));
+    if (id !== undefined) throw new Error(`Question "${question.id}" has two options with id "${id}".`);
+    if (question.allow_multiple === true && question.options.some((option) => shown(option) === DONE_LABEL)) throw new Error(`Option label "${DONE_LABEL}" is reserved for ending a multi-select question.`);
+    if (question.options.some((option) => shown(option) === OTHER_LABEL || option.id === OTHER_ID)) throw new Error(`Option label "${OTHER_LABEL}" and id "${OTHER_ID}" are reserved for the typed answer.`);
+  }
+}
+
+interface Answer {
+  ids: string[];
+  other?: string;
+}
+
+/** The typed answer behind Other; an empty or dismissed input is no answer. */
+async function typedAnswer(prompt: string, ctx: ExtensionContext): Promise<string | undefined> {
+  const text = (await ctx.ui.input(prompt))?.trim();
+  return text === undefined || text === '' ? undefined : text;
+}
+
+async function askOne(question: Question, ctx: ExtensionContext, title: string | undefined): Promise<Answer | undefined> {
+  const labelToId = new Map(question.options.map((option) => [shown(option), option.id]));
+  const prompt = title === undefined || title === '' ? question.prompt : `${title}: ${question.prompt}`;
+  if (question.allow_multiple !== true) {
+    const label = await ctx.ui.select(prompt, [...question.options.map(shown), OTHER_LABEL]);
+    if (label === OTHER_LABEL) {
+      const other = await typedAnswer(prompt, ctx);
+      return other === undefined ? undefined : { ids: [OTHER_ID], other };
+    }
+    const id = label === undefined ? undefined : labelToId.get(label);
+    return id === undefined ? undefined : { ids: [id] };
+  }
+  const picked: string[] = [];
+  let other: string | undefined;
+  const result = (): Answer => (other === undefined ? { ids: picked } : { ids: [...picked, OTHER_ID], other });
+  for (;;) {
+    const remaining = [...question.options.filter((option) => !picked.includes(option.id)).map(shown), ...(other === undefined ? [OTHER_LABEL] : [])];
+    const heading =
+      picked.length === 0 && other === undefined
+        ? `${prompt} (pick one at a time, then ${DONE_LABEL})`
+        : `${prompt} (picked: ${[...picked.map((id) => question.options.find((option) => option.id === id)?.label), ...(other === undefined ? [] : [`"${other}"`])].join(', ')})`;
+    const label = await ctx.ui.select(heading, [...remaining, DONE_LABEL]);
+    if (label === undefined) return picked.length === 0 && other === undefined ? undefined : result();
+    if (label === OTHER_LABEL) {
+      other = await typedAnswer(prompt, ctx);
+      continue;
+    }
+    const id = labelToId.get(label);
+    if (label === DONE_LABEL || id === undefined) return result();
+    picked.push(id);
+  }
+}
+
+function answerLine(question: Question, answer: Answer | undefined): string {
+  if (answer === undefined) return `${question.id}: no answer (the user dismissed the question)`;
+  const parts = answer.ids.map((id) => (id === OTHER_ID ? `other ("${answer.other}")` : `${id} (${question.options.find((option) => option.id === id)?.label ?? id})`));
+  return `${question.id}: ${parts.length === 0 ? 'none selected' : parts.join(', ')}`;
+}
+
+/** Structured questions (pstack: "Prefer AskQuestion over free text"), over Pi's select dialog. */
+export function registerAskQuestion(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'AskQuestion',
+    label: 'Ask question',
+    description:
+      'Ask the user one or more structured multiple-choice questions and wait for the answers. Each answer comes back as option IDs, or as other with the text the user typed. Use it for a genuine product or preference choice, not for a fact you can check yourself.',
+    promptSnippet: 'Structured multiple-choice questions for the user',
+    parameters: AskParams,
+    exposure: 'model-only',
+    executionMode: 'sequential',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      validateQuestions(params.questions);
+      // Print and JSON runs and subagents have no one to answer, so the questions come back skipped.
+      if (!canAsk(ctx)) {
+        const text = params.questions.map((question) => `${question.id}: ${SKIPPED}`).join('\n');
+        return { content: [{ type: 'text', text }], details: { answers: {}, skipped: params.questions.map((question) => question.id) } };
+      }
+      const answers: Record<string, string[]> = {};
+      const other: Record<string, string> = {};
+      const lines: string[] = [];
+      for (const question of params.questions) {
+        const answer = await askOne(question, ctx, params.title);
+        if (answer !== undefined) answers[question.id] = answer.ids;
+        if (answer?.other !== undefined) other[question.id] = answer.other;
+        lines.push(answerLine(question, answer));
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }], details: Object.keys(other).length === 0 ? { answers } : { answers, other } };
+    },
+  });
+}

package/src/autocomplete.ts

@@ -0,0 +1,21 @@
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from '@earendil-works/pi-tui';
+
+const COMMAND_TOKEN = /^\/([a-z0-9-]*)$/;
+
+/** Adds the `/name` skill aliases to Pi's `/` menu; everything else is Pi's. */
+export function aliasAutocomplete(current: AutocompleteProvider, aliases: ReadonlyMap<string, string>): AutocompleteProvider {
+  return {
+    ...(current.triggerCharacters === undefined ? {} : { triggerCharacters: current.triggerCharacters }),
+    async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+      const base = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+      const token = cursorLine === 0 ? COMMAND_TOKEN.exec((lines[0] ?? '').slice(0, cursorCol))?.[1] : undefined;
+      if (token === undefined) return base;
+      const mine: AutocompleteItem[] = [...aliases].filter(([name]) => name.startsWith(token)).map(([name, description]) => ({ value: name, label: name, description }));
+      if (mine.length === 0) return base;
+      const taken = new Set(mine.map((item) => item.value));
+      return { prefix: `/${token}`, items: [...mine, ...(base?.items ?? []).filter((item) => !taken.has(item.value))] };
+    },
+    applyCompletion: (lines, cursorLine, cursorCol, item, prefix) => current.applyCompletion(lines, cursorLine, cursorCol, item, prefix),
+    ...(current.shouldTriggerFileCompletion === undefined ? {} : { shouldTriggerFileCompletion: (lines: string[], cursorLine: number, cursorCol: number) => current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true }),
+  };
+}

package/src/child-env.ts

@@ -0,0 +1,44 @@
+// A subagent learns its depth, its agent type, whether it is readonly, its parent's pid, and the main chat's store and workspace state from these variables. They are read once and
+// removed, so commands the subagent runs (including a nested `pi` driven through bash) do not inherit them.
+export const DEPTH_ENV = 'PI_PSTACK_DEPTH';
+export const AGENT_ENV = 'PI_PSTACK_AGENT';
+export const PARENT_ENV = 'PI_PSTACK_PARENT_PID';
+export const READONLY_ENV = 'PI_PSTACK_READONLY';
+export const ROOT_STORE_ENV = 'PI_PSTACK_ROOT_STORE';
+export const WORKSPACE_ENV = 'PI_PSTACK_WORKSPACE_STATE';
+
+export interface ChildIdentity {
+  depth: number;
+  agentType: string | undefined;
+  parentPid: number | undefined;
+  readonly: boolean;
+  rootStore: string | undefined;
+  /** The main chat's workspace state folder, which every agent in the tree shares, an isolated worker included. */
+  workspaceState: string | undefined;
+}
+
+function read(): ChildIdentity {
+  const depth = Number(process.env[DEPTH_ENV] ?? '0');
+  const parentPid = Number(process.env[PARENT_ENV] ?? '');
+  return {
+    depth: Number.isInteger(depth) && depth > 0 ? depth : 0,
+    agentType: process.env[AGENT_ENV],
+    parentPid: Number.isInteger(parentPid) && parentPid > 1 ? parentPid : undefined,
+    readonly: process.env[READONLY_ENV] === '1',
+    rootStore: process.env[ROOT_STORE_ENV] || undefined,
+    workspaceState: process.env[WORKSPACE_ENV] || undefined,
+  };
+}
+
+export const childIdentity: ChildIdentity = read();
+delete process.env[DEPTH_ENV];
+delete process.env[AGENT_ENV];
+delete process.env[PARENT_ENV];
+delete process.env[READONLY_ENV];
+delete process.env[ROOT_STORE_ENV];
+delete process.env[WORKSPACE_ENV];
+
+/** Variables for a child of this process at `depth` (an agent keeps the depth it was created at). */
+export function childVariables(agentType: string, depth: number, readonly: boolean, rootStore: string, workspaceState: string): Record<string, string> {
+  return { [DEPTH_ENV]: String(depth), [AGENT_ENV]: agentType, [PARENT_ENV]: String(process.pid), [ROOT_STORE_ENV]: rootStore, [WORKSPACE_ENV]: workspaceState, ...(readonly ? { [READONLY_ENV]: '1' } : {}) };
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
+import { registerAskQuestion } from './ask.ts';
+import { aliasAutocomplete } from './autocomplete.ts';
+import { childIdentity } from './child-env.ts';
+import { registerLoop } from './loop.ts';
+import { registerMode } from './mode.ts';
+import { canAsk, isOneShot } from './modes.ts';
+import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
+import { registerPlanMode } from './plan.ts';
+import { registerReadonlyShell } from './readonly-shell.ts';
+import { migrateLegacyRule, modelsSection, readRule } from './rule.ts';
+import { hostSection, subagentsSection } from './sections.ts';
+import { registerSubscriptions } from './subscriptions/index.ts';
+import { type AgentDefinition, loadAgentDefinitions } from './task/agents.ts';
+import { registerAgentStatus } from './task/status.ts';
+import { availableModels, parentModel, registerTask } from './task/tool.ts';
+import { registerTodoWrite } from './todo.ts';
+import { registerVisualize } from './visualize.ts';
+
+const WATCHDOG_MS = 1_000;
+const ORPHAN_EXIT_MS = 5_000;
+
+/** In a subagent, the agent definition body joins the system prompt as the agent's own instructions. */
+function agentSection(agents: readonly AgentDefinition[]): Record<string, string> {
+  const prompt = agents.find((agent) => agent.type === childIdentity.agentType)?.prompt ?? '';
+  return prompt === '' ? {} : { pstack_agent: prompt };
+}
+
+function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly AgentDefinition[]): Record<string, string> {
+  const activeTools = pi.getActiveTools();
+  return {
+    pstack_host: hostSection({
+      packageRoot: PACKAGE_ROOT,
+      skillsDir: SKILLS_DIR,
+      skillNames: packageSkillNames(pi.getCommands()),
+      agentDir: getAgentDir(),
+      rulePath: rulePath(),
+      sessionDir: ctx.sessionManager.getSessionDir(),
+      sessionFile: ctx.sessionManager.getSessionFile(),
+      subagentDir: subagentDir(ctx.cwd),
+      storeDir: storeDir(ctx.cwd, ctx.sessionManager.getSessionId()),
+      rootStoreDir: rootStoreDir(ctx.cwd, ctx.sessionManager.getSessionId(), childIdentity.rootStore),
+      projectsDir: projectsDir(ctx.cwd),
+      artifactsDir: artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()),
+      loopAvailable: !isOneShot(ctx.mode),
+      questionsAvailable: canAsk(ctx),
+      activeTools,
+    }),
+    ...(activeTools.includes('Task') ? { pstack_subagents: subagentsSection(agents, availableModels(ctx), parentModel(ctx)) } : {}),
+    pstack_models: modelsSection(readRule(rulePath()), rulePath()),
+    ...agentSection(agents),
+  };
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * A subagent runs in its own process group so abort and shutdown can stop everything it started, which also means
+ * it outlives a parent that crashes or is killed. The subagent therefore exits once its parent is gone. Normally the
+ * parent Pi is the direct parent, and a live `process.ppid` change (the OS reparents an orphan) cannot be fooled by a
+ * reused pid. When a launcher that does not exec sits in between, the parent pid is checked as well.
+ */
+function watchParent(pi: ExtensionAPI, parentPid: number): void {
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const initialParent = process.ppid;
+  const parentGone = () => process.ppid !== initialParent || (initialParent !== parentPid && !alive(parentPid));
+  pi.on('session_start', (_event, ctx) => {
+    timer = setInterval(() => {
+      if (!parentGone()) return;
+      clearInterval(timer);
+      ctx.abort();
+      ctx.shutdown();
+      setTimeout(() => process.exit(0), ORPHAN_EXIT_MS).unref();
+    }, WATCHDOG_MS);
+    timer.unref();
+  });
+  pi.on('session_shutdown', () => clearInterval(timer));
+}
+
+export default function piPstack(pi: ExtensionAPI): void {
+  const agents = loadAgentDefinitions();
+
+  pi.on('input', (event) => aliasInputResult(event, new Set(aliasTable(pi.getCommands()).keys())));
+  pi.on('session_start', (_event, ctx) => {
+    if (ctx.mode === 'tui') ctx.ui.addAutocompleteProvider((current) => aliasAutocomplete(current, aliasTable(pi.getCommands())));
+  });
+
+  const mode = registerMode(pi);
+  const plan = registerPlanMode(pi);
+  registerVisualize(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()) });
+  const task = registerTask(pi, { agents, depth: childIdentity.depth, planMode: plan.enabled });
+  registerAgentStatus(pi);
+  registerSubscriptions(pi, { runFresh: async (prompt, name) => void (await task.startBackground(`timer ${name}`, prompt)) });
+  const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
+  registerTodoWrite(pi);
+  registerAskQuestion(pi);
+  if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);
+  if (childIdentity.readonly) registerReadonlyShell(pi);
+
+  pi.on('before_agent_start', (event, ctx) => {
+    const modeText = mode.section();
+    const loopText = loop.section();
+    const planText = plan.section();
+    Object.assign(
+      event.systemPromptOptions.sections,
+      hostSections(pi, ctx, agents),
+      modeText === undefined ? {} : { pstack_mode: modeText },
+      loopText === undefined ? {} : { pstack_loop: loopText },
+      planText === undefined ? {} : { pstack_plan: planText },
+    );
+  });
+
+  pi.on('session_start', () => migrateLegacyRule(rulePath()));
+}