@preapexis/piexis 0.2.2 → 0.2.5

package/lib/question-model.ts

@@ -0,0 +1,98 @@
+import { Type, type Static } from "typebox";
+
+const Option = Type.Object({
+  id: Type.Optional(Type.String({ minLength: 1 })),
+  label: Type.String({ minLength: 1 }),
+  description: Type.Optional(Type.String())
+});
+
+export const AskQuestionParams = Type.Object({
+  questions: Type.Array(Type.Object({
+    id: Type.Optional(Type.String({ minLength: 1 })),
+    question: Type.String({ minLength: 1 }),
+    type: Type.Optional(Type.Union([Type.Literal("single"), Type.Literal("multi"), Type.Literal("text")])),
+    options: Type.Optional(Type.Array(Option)),
+    multiSelect: Type.Optional(Type.Boolean()),
+    allowOther: Type.Optional(Type.Boolean()),
+    required: Type.Optional(Type.Boolean()),
+    defaultSelection: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+    minSelections: Type.Optional(Type.Integer({ minimum: 0 })),
+    maxSelections: Type.Optional(Type.Integer({ minimum: 0 })),
+    maxLength: Type.Optional(Type.Integer({ minimum: 0 }))
+  }), { minItems: 1, description: "Related questions, answered together in the terminal" })
+});
+
+export type Params = Static<typeof AskQuestionParams>;
+export type Question = Omit<Params["questions"][number], "id" | "type" | "options" | "required"> & {
+  id: string;
+  type: "single" | "multi" | "text";
+  options: { id: string; label: string; description?: string }[];
+  required: boolean;
+};
+export type Draft = { indices: number[]; text: string; custom: boolean };
+export type Answer = {
+  id: string;
+  question: string;
+  answer: string | string[] | null;
+  optionIds: string[];
+  custom: boolean;
+};
+export type Outcome = "answered" | "cancelled" | "aborted" | "requires_interaction" | "error";
+export type Result = { status: Outcome; answers: Answer[]; cancelled: boolean; error?: string };
+
+export function normalizeQuestions(params: Params): Question[] {
+  if (!params.questions.length) throw new Error("At least one question is required.");
+  const questions = params.questions.map((item, index): Question => {
+    const type = item.type ?? (item.options?.length ? item.multiSelect ? "multi" : "single" : "text");
+    const options = (item.options ?? []).map((option, i) => ({ ...option, id: option.id ?? `option-${i + 1}` }));
+    if (!item.question.trim()) throw new Error("Question text cannot be blank.");
+    if (new Set(options.map((option) => option.id)).size !== options.length) throw new Error("Option IDs must be unique within each question.");
+    if (options.some((option) => !option.label.trim())) throw new Error("Option labels cannot be blank.");
+    if (item.type && item.multiSelect && item.type !== "multi") throw new Error("type conflicts with multiSelect.");
+    if (type === "text" && options.length) throw new Error("Text questions cannot have options.");
+    if (!options.length && type !== "text") throw new Error("Selection questions require options.");
+    // Legacy optionless questions still require explicit permission for text input.
+    if (!item.type && !options.length && !item.allowOther) throw new Error("AskQuestion requires options or allowOther=true.");
+    const required = item.required !== false;
+    const min = Math.max(item.minSelections ?? 0, required ? 1 : 0);
+    const max = item.maxSelections ?? options.length;
+    if (type !== "multi" && (item.minSelections !== undefined || item.maxSelections !== undefined)) throw new Error("Selection limits require a multi question.");
+    if (type === "multi" && (min > max || max > options.length)) throw new Error("Invalid selection limits.");
+    const q = { ...item, id: item.id ?? `question-${index + 1}`, type, options, required };
+    const defaults = item.defaultSelection === undefined ? [] : typeof item.defaultSelection === "string" ? [item.defaultSelection] : item.defaultSelection;
+    if (type === "text" && defaults.length) throw new Error("Text questions do not support defaultSelection.");
+    if (type === "single" && defaults.length > 1) throw new Error("Single questions accept only one default selection.");
+    if (defaults.some((id) => !options.some((option) => option.id === id))) throw new Error("Unknown default option ID.");
+    return q;
+  });
+  if (new Set(questions.map((q) => q.id)).size !== questions.length) throw new Error("Question IDs must be unique.");
+  return questions;
+}
+
+export function initialDraft(q: Question): Draft {
+  const defaults = q.defaultSelection === undefined ? [] : typeof q.defaultSelection === "string" ? [q.defaultSelection] : q.defaultSelection;
+  return { indices: q.options.flatMap((option, i) => defaults.includes(option.id) ? [i] : []), text: "", custom: q.type === "text" };
+}
+
+/** Shared by submission and final review; never filters away invalid selections. */
+export function validateAnswer(q: Question, draft: Draft): Answer {
+  if (draft.custom) {
+    if (q.type !== "text" && !q.allowOther) throw new Error("Custom answers are not enabled.");
+    if (q.required && !draft.text.trim()) throw new Error("An answer is required.");
+    if (q.maxLength !== undefined && Array.from(draft.text).length > q.maxLength) throw new Error(`Use at most ${q.maxLength} characters.`);
+    return { id: q.id, question: q.question, answer: draft.text, optionIds: [], custom: true };
+  }
+  if (q.type === "text") throw new Error("Enter a text answer.");
+  if (draft.indices.some((i) => !Number.isInteger(i) || i < 0 || i >= q.options.length)) throw new Error("Choose only listed options.");
+  const indices = [...new Set(draft.indices)].sort((a, b) => a - b);
+  const min = q.type === "multi" ? Math.max(q.minSelections ?? 0, q.required ? 1 : 0) : q.required ? 1 : 0;
+  const max = q.type === "multi" ? q.maxSelections ?? q.options.length : 1;
+  if (indices.length < min) throw new Error(`Choose at least ${min} option${min === 1 ? "" : "s"}.`);
+  if (indices.length > max) throw new Error(`Choose at most ${max} option${max === 1 ? "" : "s"}.`);
+  const options = indices.map((i) => q.options[i]!);
+  return { id: q.id, question: q.question, answer: q.type === "multi" ? options.map((o) => o.label) : options[0]?.label ?? "", optionIds: options.map((o) => o.id), custom: false };
+}
+
+export function outcome(status: Outcome, answers: Answer[] = [], error?: string): Result {
+  return { status, answers, cancelled: status !== "answered", ...(error ? { error } : {}) };
+}

package/lib/question-ui.ts

@@ -0,0 +1,214 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Input, Key, matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { initialDraft, outcome, validateAnswer, type Answer, type Draft, type Outcome, type Question, type Result } from "./question-model.ts";
+
+// Model-provided labels are plain text, not terminal escape sequences.
+const plain = (text: string) => text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+export class QuestionScreen {
+  private current = 0;
+  private review = false;
+  private error = "";
+  private settled = false;
+  private hasFocus = false;
+  private readonly drafts: Draft[];
+  private readonly inputs: Input[];
+  private readonly focus: number[];
+  private readonly confirmed = new Set<number>();
+  private readonly abort = () => this.finish("aborted");
+  private readonly eof = () => this.finish("error", "Terminal input closed before submission.");
+  private readonly inputError = (error: Error) => this.finish("error", `Terminal input failed: ${message(error)}`);
+
+  private readonly questions: Question[];
+  private readonly tui: Pick<TUI, "requestRender" | "terminal">;
+  private readonly theme: Pick<Theme, "fg">;
+  private readonly done: (result: Result) => void;
+  private readonly signal?: AbortSignal;
+  private readonly stream: Pick<NodeJS.ReadStream, "on" | "off">;
+
+  constructor(
+    questions: Question[],
+    tui: Pick<TUI, "requestRender" | "terminal">,
+    theme: Pick<Theme, "fg">,
+    done: (result: Result) => void,
+    signal?: AbortSignal,
+    stream: Pick<NodeJS.ReadStream, "on" | "off"> = process.stdin
+  ) {
+    this.questions = questions;
+    this.tui = tui;
+    this.theme = theme;
+    this.done = done;
+    this.signal = signal;
+    this.stream = stream;
+    this.drafts = questions.map(initialDraft);
+    this.focus = this.drafts.map((draft) => draft.indices[0] ?? 0);
+    this.inputs = questions.map(() => new Input({ prompt: "> " }));
+    signal?.addEventListener("abort", this.abort, { once: true });
+    stream.on("end", this.eof);
+    stream.on("close", this.eof);
+    stream.on("error", this.inputError);
+    if (signal?.aborted) this.abort();
+  }
+
+  get focused() { return this.hasFocus; }
+  set focused(value: boolean) {
+    this.hasFocus = value;
+    this.inputs.forEach((input, i) => { input.focused = value && !this.review && i === this.current && this.drafts[i]!.custom; });
+  }
+
+  dispose() {
+    this.signal?.removeEventListener("abort", this.abort);
+    this.stream.off("end", this.eof);
+    this.stream.off("close", this.eof);
+    this.stream.off("error", this.inputError);
+    this.inputs.forEach((input) => { input.focused = false; });
+  }
+
+  private answers(): Answer[] {
+    return this.questions.flatMap((q, i) => this.confirmed.has(i) ? [validateAnswer(q, this.drafts[i]!)] : []);
+  }
+
+  private finish(status: Outcome, error?: string) {
+    if (this.settled) return;
+    this.settled = true;
+    this.dispose();
+    this.done(outcome(status, this.answers(), error));
+  }
+
+  private refresh() {
+    this.focused = this.hasFocus;
+    this.tui.requestRender();
+  }
+
+  private save() {
+    try {
+      validateAnswer(this.questions[this.current]!, this.drafts[this.current]!);
+      this.confirmed.add(this.current);
+      this.error = "";
+      if (this.questions.length === 1) this.finish("answered");
+      else if (this.current + 1 < this.questions.length) this.current++;
+      else this.review = true;
+    } catch (error) {
+      this.error = message(error);
+    }
+  }
+
+  handleInput(data: string) {
+    if (this.settled) return;
+    try {
+      if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+        this.finish("cancelled");
+        return;
+      }
+      if (this.questions.length > 1 && (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab")))) {
+        const position = this.review ? this.questions.length : this.current;
+        const direction = matchesKey(data, Key.tab) ? 1 : -1;
+        const next = (position + direction + this.questions.length + 1) % (this.questions.length + 1);
+        this.review = next === this.questions.length;
+        if (!this.review) this.current = next;
+        this.error = "";
+      } else if (this.review) {
+        if (matchesKey(data, Key.enter)) {
+          const missing = this.questions.findIndex((_, i) => !this.confirmed.has(i));
+          if (missing !== -1) {
+            this.current = missing;
+            this.review = false;
+            this.error = "Confirm this question before submitting.";
+          } else {
+            this.questions.forEach((q, i) => validateAnswer(q, this.drafts[i]!));
+            this.finish("answered");
+          }
+        }
+      } else {
+        const q = this.questions[this.current]!;
+        const draft = this.drafts[this.current]!;
+        const input = this.inputs[this.current]!;
+        if (draft.custom) {
+          if (q.type !== "text" && matchesKey(data, Key.up)) {
+            draft.custom = false;
+            this.confirmed.delete(this.current);
+          } else if (matchesKey(data, Key.enter)) {
+            this.save();
+          } else {
+            input.handleInput(data);
+            draft.text = input.getValue();
+            this.confirmed.delete(this.current);
+            this.error = "";
+          }
+        } else {
+          // The synthetic action lives at a separate index, never a label or option ID.
+          const count = q.options.length + (q.allowOther ? 1 : 0) + (!q.required && q.type === "single" ? 1 : 0);
+          let focus = this.focus[this.current]!;
+          if (matchesKey(data, Key.up)) this.focus[this.current] = (focus - 1 + count) % count;
+          else if (matchesKey(data, Key.down)) this.focus[this.current] = (focus + 1) % count;
+          else if (q.type === "multi" && matchesKey(data, Key.space) && focus < q.options.length) {
+            draft.indices = draft.indices.includes(focus) ? draft.indices.filter((i) => i !== focus) : [...draft.indices, focus];
+            this.confirmed.delete(this.current);
+            this.error = "";
+          } else if (matchesKey(data, Key.enter) || (q.type === "multi" && matchesKey(data, Key.space))) {
+            if (q.allowOther && focus === q.options.length) {
+              draft.custom = true;
+              this.confirmed.delete(this.current);
+            } else {
+              if (q.type === "single") draft.indices = focus < q.options.length ? [focus] : [];
+              this.save();
+            }
+          }
+        }
+      }
+      this.refresh();
+    } catch (error) {
+      this.finish("error", message(error));
+    }
+  }
+
+  invalidate() { this.inputs.forEach((input) => input.invalidate()); }
+
+  render(width: number): string[] {
+    if (this.settled) return [];
+    try {
+      width = Math.max(1, width);
+      const lines: string[] = [];
+      const add = (text: string, color: Parameters<Theme["fg"]>[0] = "text") => lines.push(truncateToWidth(this.theme.fg(color, plain(text)), width));
+      add(this.review ? "✓ Review answers · Enter to submit" : `? Question ${this.current + 1}/${this.questions.length}`, "accent");
+      if (this.review) {
+        this.questions.forEach((q, i) => {
+          const value = this.confirmed.has(i) ? validateAnswer(q, this.drafts[i]!).answer : "(not confirmed)";
+          add(`${q.question}: ${Array.isArray(value) ? value.join(", ") : value}`);
+        });
+      } else {
+        const q = this.questions[this.current]!;
+        const draft = this.drafts[this.current]!;
+        add(q.question);
+        if (draft.custom) {
+          add(q.type === "text" ? "Your answer:" : "Your answer · ↑ returns to options", "muted");
+          lines.push(...this.inputs[this.current]!.render(width));
+        } else {
+          const choices = q.options.map((option, i) => ({ label: option.label, description: option.description, selected: draft.indices.includes(i) }));
+          if (q.allowOther) choices.push({ label: "Type something else", description: undefined, selected: false });
+          if (!q.required && q.type === "single") choices.push({ label: "Skip (no answer)", description: undefined, selected: false });
+          // Bound menu height to the terminal and keep the focused choice visible.
+          const capacity = Math.max(1, Math.floor((this.tui.terminal.rows - 9) / 2));
+          const start = Math.max(0, Math.min(this.focus[this.current]! - Math.floor(capacity / 2), choices.length - capacity));
+          choices.slice(start, start + capacity).forEach((choice, offset) => {
+            const i = start + offset;
+            const focused = i === this.focus[this.current];
+            add(`${focused ? "❯" : " "} ${q.type === "multi" ? choice.selected ? "[x] " : "[ ] " : ""}${i + 1}. ${choice.label}`, focused ? "accent" : "text");
+            if (choice.description) add(`     ${choice.description}`, "muted");
+          });
+          if (choices.length > capacity) add(`${start + 1}–${Math.min(start + capacity, choices.length)} of ${choices.length}`, "dim");
+        }
+      }
+      if (this.error) add(this.error, "error");
+      const multi = !this.review && this.questions[this.current]!.type === "multi" && !this.drafts[this.current]!.custom;
+      const textMode = !this.review && this.drafts[this.current]!.custom;
+      add(`${this.review || textMode ? "" : multi ? "↑↓ Navigate · Space Toggle · " : "↑↓ Navigate · "}Enter Confirm · Esc/Ctrl+C Cancel`, "dim");
+      if (this.questions.length > 1) add("Tab/Shift+Tab Questions · Answers preserved", "dim");
+      return lines;
+    } catch (error) {
+      this.finish("error", message(error));
+      return [];
+    }
+  }
+}

package/lib/recommended-tools.ts

@@ -0,0 +1,119 @@
+import { getAgentDir, SettingsManager, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+export const recommendedTools = ["grep", "find", "ls"];
+const defaultTools = ["read", "bash", "edit", "write"];
+// Older Pi releases treat +name as a literal tool name.
+export const supportsAdditiveTools = SettingsManager.inMemory({ defaultTools: ["+find"] }).getDefaultTools()?.includes("find") === true;
+type Settings = Record<string, unknown>;
+type Snapshot = { text: string | undefined; settings: Settings; mode: number };
+export type SetupSettings = { projectPath: string; globalPath: string; project: Snapshot; global: Snapshot };
+
+function object(value: unknown): value is Settings {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function snapshot(path: string): Promise<Snapshot> {
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile()) throw new Error(`Not a regular settings file: ${path}`);
+    const text = await readFile(path, "utf8");
+    const settings: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
+    if (!object(settings)) throw new Error(`Settings must be a JSON object: ${path}`);
+    if (settings.defaultTools !== undefined && (!Array.isArray(settings.defaultTools) || settings.defaultTools.some((entry) => typeof entry !== "string" || !entry))) {
+      throw new Error(`Invalid defaultTools in ${path}`);
+    }
+    if (settings.piexis !== undefined && !object(settings.piexis)) throw new Error(`Invalid piexis settings in ${path}`);
+    return { text, settings, mode: stat.mode & 0o777 };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { text: undefined, settings: {}, mode: 0o600 };
+    throw error;
+  }
+}
+
+export async function readSetupSettings(cwd: string, agentDir = getAgentDir()): Promise<SetupSettings> {
+  const projectPath = join(cwd, ".pi", "settings.json");
+  const globalPath = join(agentDir, "settings.json");
+  const directories = await Promise.all([dirname(projectPath), dirname(globalPath)].map(async (path) => {
+    try { return await realpath(path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return resolve(path);
+      throw error;
+    }
+  }));
+  if (directories[0] === directories[1]) throw new Error("Project and user settings share a path; project-only setup is unavailable.");
+  const [project, global] = await Promise.all([snapshot(projectPath), snapshot(globalPath)]);
+  return { projectPath, globalPath, project, global };
+}
+
+export function setupChoice(settings: SetupSettings, feature: "recommendedTools" | "agentSetup" = "recommendedTools"): unknown {
+  const piexis = settings.project.settings.piexis;
+  return object(piexis) ? piexis[feature] : undefined;
+}
+
+export function toolsToOffer(settings: SetupSettings, available: string[], active: string[], additive = supportsAdditiveTools): string[] {
+  if (setupChoice(settings) === "enabled" || setupChoice(settings) === "disabled") return [];
+  const layers = [settings.global.settings.defaultTools, settings.project.settings.defaultTools] as (string[] | undefined)[];
+  // A plain-name list (including []) is an intentional allowlist, not an invitation to expand it.
+  if (layers.some((list) => list !== undefined && (!list.length || list.some((name) => !/^[+-].+/.test(name))))) return [];
+  // Do not reinterpret additive configurations on a Pi release that does not support them.
+  if (!additive && layers.some((list) => list !== undefined)) return [];
+  const excluded = new Set<string>();
+  for (const list of layers) {
+    for (const entry of list ?? []) {
+      if (entry.startsWith("-")) excluded.add(entry.slice(1));
+      else excluded.delete(entry.slice(1));
+    }
+  }
+  return recommendedTools.filter((name) => available.includes(name) && !active.includes(name) && !excluded.has(name));
+}
+
+/** Skip CLI selection overrides instead of trying to infer or undo the user's policy. */
+export function hasToolOverrides(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === "--") break;
+    if (/^(?:--(?:tools|exclude-tools|no-tools|no-builtin-tools)|-t|-xt|-nt|-nbt)(?:=|$)/.test(arg)) return true;
+  }
+  return false;
+}
+
+export async function saveSetupChoice(settings: SetupSettings, choice: "enabled" | "disabled", tools: string[], additive = supportsAdditiveTools, signal?: AbortSignal, agentSetup?: "enabled" | "disabled"): Promise<void> {
+  await withFileMutationQueue(settings.projectPath, async () => {
+    signal?.throwIfAborted();
+    await mkdir(dirname(settings.projectPath), { recursive: true });
+    // Use Pi's settings lock-directory convention. Never remove another writer's lock.
+    const lock = `${settings.projectPath}.lock`;
+    await mkdir(lock);
+    const temporary = join(dirname(settings.projectPath), `.settings.json.piexis-${randomUUID()}.tmp`);
+    try {
+      const { project, global } = await readSetupSettings(dirname(dirname(settings.projectPath)), dirname(settings.globalPath));
+      if (project.text !== settings.project.text || global.text !== settings.global.text) {
+        throw new Error("Settings changed while the setup prompt was open. Nothing was overwritten; try again next startup.");
+      }
+      signal?.throwIfAborted();
+      const next = { ...project.settings };
+      const piexis = object(next.piexis) ? next.piexis : {};
+      next.piexis = { ...piexis,
+        ...(tools.length ? { recommendedTools: choice } : {}),
+        ...(agentSetup ? { agentSetup } : {}),
+      };
+      if (choice === "enabled" && tools.length) {
+        next.defaultTools = additive
+          ? [...(project.settings.defaultTools as string[] | undefined ?? []), ...tools.map((name) => `+${name}`)]
+          : [...defaultTools, ...tools];
+      }
+      await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { flag: "wx", mode: project.mode });
+      await chmod(temporary, project.mode);
+      signal?.throwIfAborted();
+      await rename(temporary, settings.projectPath);
+    } finally {
+      try {
+        await rm(temporary, { force: true });
+      } finally {
+        await rm(lock, { recursive: true, force: true });
+      }
+    }
+  });
+}

package/lib/subagent-runner.ts

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+type Usage = NonNullable<Awaited<ReturnType<ToolDefinition["execute"]>>["usage"]>;
+
+export function emptyUsage(): Usage {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+}
+
+export function addUsage(total: Usage, value?: Partial<Usage>): void {
+  for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+    if (typeof value?.[key] === "number" && Number.isFinite(value[key])) total[key] += value[key];
+  }
+  for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+    if (typeof value?.cost?.[key] === "number" && Number.isFinite(value.cost[key])) total.cost[key] += value.cost[key];
+  }
+}
+
+export function piInvocation(): { command: string; args: string[] } {
+  const script = process.argv[1];
+  if (script && /(?:^|[\\/])(?:cli|pi)\.(?:m?js|ts)$/.test(script) && existsSync(script)) {
+    return { command: process.execPath, args: [script] };
+  }
+  if (!/^(node|bun)(\.exe)?$/i.test(basename(process.execPath))) return { command: process.execPath, args: [] };
+  const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+  const cli = join(dirname(entry), "bundle", "cli.js");
+  return existsSync(cli) ? { command: process.execPath, args: [cli] } : { command: "pi", args: [] };
+}
+
+export interface ChildResult {
+  output: string;
+  exitCode: number;
+  stopReason?: string;
+  error?: string;
+  stderr: string;
+  usage: Usage;
+}
+
+export function limitOutput(text: string, limit = 50_000): string {
+  return text.length > limit ? `${text.slice(0, limit)}\n[Output truncated; full output is in subagent tool details (up to 1 MB).]` : text;
+}
+
+export async function runSubagent(options: {
+  invocation: { command: string; args: string[] };
+  args: string[];
+  cwd: string;
+  depth: number;
+  task: string;
+  signal: AbortSignal;
+  onProgress?: (text: string) => void;
+}): Promise<ChildResult> {
+  options.signal.throwIfAborted();
+  const result: ChildResult = { output: "", exitCode: -1, stderr: "", usage: emptyUsage() };
+  return new Promise((resolve, reject) => {
+    const grouped = process.platform !== "win32" && options.depth === 1;
+    const child = spawn(options.invocation.command, [...options.invocation.args, ...options.args], {
+      cwd: options.cwd, shell: false, detached: grouped,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, PIEXIS_SUBAGENT_DEPTH: String(options.depth) },
+    });
+    let buffer = "", bytes = 0, timer: NodeJS.Timeout | undefined, failure: Error | undefined;
+    let closed = false;
+    const kill = (signal: NodeJS.Signals) => {
+      try {
+        if (grouped && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ESRCH") failure ??= error as Error;
+      }
+    };
+    const stop = () => {
+      kill("SIGTERM");
+      timer ??= setTimeout(() => kill("SIGKILL"), 1000);
+    };
+    const abort = () => stop();
+    options.signal.addEventListener("abort", abort, { once: true });
+    if (options.signal.aborted) abort();
+
+    const line = (text: string) => {
+      if (!text.trim()) return;
+      let event;
+      try { event = JSON.parse(text); }
+      catch { failure ??= new Error("Invalid JSON from subagent stdout"); stop(); return; }
+      if (event.type === "message_end" && event.message) {
+        const message = event.message;
+        if (message.role === "assistant" || message.role === "toolResult") addUsage(result.usage, message.usage);
+        if (message.role === "assistant") {
+          result.output = (Array.isArray(message.content) ? message.content : [])
+            .filter((part: { type: string }) => part.type === "text")
+            .map((part: { text: string }) => part.text).join("\n");
+          if (result.output.length > 1_000_000) result.output = `${result.output.slice(0, 1_000_000)}\n[Output exceeded the 1 MB retention limit.]`;
+          result.stopReason = message.stopReason;
+          result.error = message.errorMessage;
+          options.onProgress?.(limitOutput(result.output, 2000) || "Working…");
+        }
+      } else if (event.type === "tool_execution_start") {
+        options.onProgress?.(`Running ${event.toolName}…`);
+      } else if (event.type === "agent_settled" && event.aborted) {
+        result.stopReason = "aborted";
+      }
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (data: string) => {
+      if (failure) return;
+      bytes += Buffer.byteLength(data);
+      buffer += data;
+      if (bytes > 64 * 1024 * 1024 || buffer.length > 8 * 1024 * 1024) {
+        failure = new Error("Subagent event stream exceeded its limit"); stop(); return;
+      }
+      let end: number;
+      while ((end = buffer.indexOf("\n")) >= 0) {
+        line(buffer.slice(0, end));
+        buffer = buffer.slice(end + 1);
+        if (failure) break;
+      }
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (text: string) => { result.stderr = (result.stderr + text).slice(-32_000); });
+    child.stdin.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code !== "EPIPE") { failure = error; stop(); }
+    });
+    child.on("error", (error) => { failure = error; });
+    child.on("close", (code, signal) => {
+      closed = true;
+      options.signal.removeEventListener("abort", abort);
+      if (!failure && buffer.trim()) line(buffer);
+      if (timer) clearTimeout(timer);
+      // A root cancellation must also terminate descendants that outlive the Pi process.
+      if (grouped && (options.signal.aborted || failure || code !== 0 || signal)) kill("SIGKILL");
+      if (options.signal.aborted) reject(new Error("Subagent aborted", { cause: options.signal.reason }));
+      else if (failure) reject(failure);
+      else {
+        result.exitCode = code ?? 1;
+        if (signal) result.error ??= `Subagent terminated by ${signal}`;
+        if (!result.output && !result.error) result.error = result.stderr || "Subagent exited without a final text response";
+        resolve(result);
+      }
+    });
+    // stdin avoids command-line size limits and keeps delegated context out of process arguments.
+    if (!closed) child.stdin.end(`Task:\n${options.task}\n`);
+  });
+}

package/lib/ui-tips.json

@@ -0,0 +1,41 @@
+[
+  { "category": "Getting started", "text": "Use /init to initialize project guidance in AGENTS.md." },
+  { "category": "Coding", "text": "For ponytail, say: \"Use ponytail: make the smallest complete change.\"" },
+  { "category": "Style", "text": "For caveman, say: \"Be brief\" or \"caveman mode\"; say \"normal mode\" to stop." },
+  { "category": "Planning", "text": "For grilling, ask: \"Turn this idea into a spec and clarify the unknowns.\"" },
+  { "category": "Coding", "text": "For lean-build, ask: \"Implement this feature with these acceptance criteria.\"" },
+  { "category": "Coding", "text": "For diagnosing-bugs, ask: \"Find the cause of this bug before fixing it.\"" },
+  { "category": "Coding", "text": "For code-review, ask: \"Review this diff for correctness.\"" },
+  { "category": "Coding", "text": "For safe-refactor, ask: \"Refactor this code without changing its behavior.\"" },
+  { "category": "Coding", "text": "For tdd, ask: \"Use test-first development: red, green, refactor.\"" },
+  { "category": "Coding", "text": "For verify-and-stop, ask: \"Verify this work against the acceptance criteria; don't expand scope.\"" },
+  { "category": "Planning", "text": "For codebase-design, ask: \"Design module boundaries and interfaces for this service.\"" },
+  { "category": "Coding", "text": "For migration, ask: \"Implement this migration with compatibility checks and rollback.\"" },
+  { "category": "Design & integrations", "text": "For frontend-design, ask: \"Design a responsive, accessible web interface.\"" },
+  { "category": "Design & integrations", "text": "For webapp-testing, ask: \"Test this local web app with Playwright.\"" },
+  { "category": "Documents", "text": "For docx, ask: \"Create a Word document with headings and a table of contents.\"" },
+  { "category": "Documents", "text": "For pdf, ask: \"Extract the text and tables from this PDF.\"" },
+  { "category": "Documents", "text": "For xlsx, ask: \"Create an Excel spreadsheet with these formulas.\"" },
+  { "category": "Documents", "text": "For pptx, ask: \"Create a presentation deck from this outline.\"" },
+  { "category": "Design & integrations", "text": "For mcp-builder, ask: \"Build an MCP server for this API.\"" },
+  { "category": "Planning", "text": "For writing-for-agents, ask: \"Improve the routing and structure of this AGENTS.md.\"" },
+  { "category": "Getting started", "text": "For find-skills, ask: \"Find an installable skill for this task.\"" },
+  { "category": "Workflow", "text": "Use /summary for a concise summary of work, decisions, and next steps." },
+  { "category": "Workflow", "text": "Use /commit to write a commit message from your Git changes; it does not commit them." },
+  { "category": "Planning", "text": "Name relevant files, constraints, and expected behavior in your prompt." },
+  { "category": "Getting started", "text": "Choose Enable if grep/find/ls setup is offered to save your project preference." },
+  { "category": "Planning", "text": "Give acceptance criteria when asking for a feature so the agent knows when to stop." },
+  { "category": "Getting started", "text": "Use /help to discover Pi commands and keyboard shortcuts." },
+  { "category": "Getting started", "text": "Use /reload after updating PieXis resources." },
+  { "category": "Interaction", "text": "In AskQuestion, use arrows to navigate, Space to toggle, Enter to confirm, and Esc to cancel." },
+  { "category": "Interaction", "text": "In AskQuestion, Tab revisits related questions without losing your drafts." },
+  { "category": "Session stats", "text": "Footer: the chat bubble counts user messages across the whole session." },
+  { "category": "Session stats", "text": "Footer: the lightning icon shows the cache-hit percentage for the current branch." },
+  { "category": "Session stats", "text": "Footer: cost is an estimate, not your provider's billing total." },
+  { "category": "Session stats", "text": "Context: the bar turns yellow at 70% and red at 90%." },
+  { "category": "Session stats", "text": "Token and cost totals follow the current conversation branch." },
+  { "category": "Getting started", "text": "Tips change on startup or reload, not on every screen redraw." },
+  { "category": "Getting started", "text": "Describe your task naturally; matching available skills can be selected automatically, but selection is not guaranteed." },
+  { "category": "Getting started", "text": "Say \"use the code-review skill\" to request a skill by name without a slash command." },
+  { "category": "Getting started", "text": "Only skills marked disable-model-invocation: true require explicit commands; none bundled here have that flag." }
+]