pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/pi/ask.ts

@@ -0,0 +1,87 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+
+import type { OneShot } from "./one-shot.ts";
+
+export const OTHER = "Other (type an answer)";
+export const DONE = "Done";
+
+const question = Type.Object(
+  {
+    question: Type.String({ description: "The complete question to ask the user" }),
+    header: Type.Optional(Type.String({ description: "Very short label for the question (max 12 chars)" })),
+    options: Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()) }), { minItems: 2, maxItems: 4 }),
+    multiSelect: Type.Optional(Type.Boolean({ description: "Allow more than one answer" })),
+  },
+);
+type Question = Static<typeof question>;
+const questionParams = Type.Object({ questions: Type.Array(question, { minItems: 1, maxItems: 4 }) });
+
+type Ui = ExtensionContext["ui"];
+
+// undefined means the user dismissed the dialog.
+async function ask(ui: Ui, q: Question, signal: AbortSignal | undefined): Promise<string | undefined> {
+  const title = q.header ? `${q.header}: ${q.question}` : q.question;
+  // Pi returns the displayed string, so number choices to distinguish them
+  // from controls and from other choices with the same rendered text.
+  const labels = new Map(q.options.map((o, i) => [`${i + 1}. ${o.label}${o.description ? ` - ${o.description}` : ""}`, o.label]));
+  // The label of a listed pick, or what the user types for OTHER.
+  const answer = (pick: string) => (pick === OTHER ? ui.input(title, "Your answer", { signal }) : labels.get(pick));
+  if (!q.multiSelect) {
+    const pick = await ui.select(title, [...labels.keys(), OTHER], { signal });
+    return pick === undefined ? undefined : answer(pick);
+  }
+  const picked = new Set<string>();
+  const chosen: string[] = [];
+  for (;;) {
+    const remaining = [...labels.keys()].filter((text) => !picked.has(text));
+    const pick = await ui.select(`${title} (one at a time; ${DONE} when finished)`, [...remaining, OTHER, DONE], { signal });
+    if (pick === undefined) return undefined;
+    if (pick === DONE) return chosen.join(", ");
+    const text = await answer(pick);
+    if (text === undefined) return undefined;
+    picked.add(pick);
+    chosen.push(text);
+  }
+}
+
+// model-only exposure keeps the tool declared under codemode.mode "only".
+export function registerAsk(pi: ExtensionAPI, oneShot: OneShot): void {
+  pi.registerTool({
+    name: "ask_user_question",
+    label: "Ask user",
+    exposure: "model-only",
+    description:
+      "Ask the user 1-4 structured questions, each with 2-4 options; the user can also type their own answer. Use it for genuine preference calls the user must make.",
+    parameters: questionParams,
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      // An rpc child reports a UI, but its parent cancels every dialog, so asking
+      // could only report a dismissal.
+      if (!ctx.hasUI || oneShot.exits(ctx)) {
+        throw new Error(
+          "ask_user_question needs an interactive UI, and this session has none. Ask the user in plain text instead and wait for the reply.",
+        );
+      }
+      const answers: { question: string; answer: string }[] = [];
+      for (const q of params.questions) {
+        const answer = await ask(ctx.ui, q, signal);
+        if (answer === undefined) break;
+        answers.push({ question: q.question, answer });
+      }
+      const dismissed = answers.length < params.questions.length;
+      const text = answers.map((a) => `"${a.question}"="${a.answer}"`).join(", ");
+      // Pi sends content to the model; details alone cannot preserve earlier answers.
+      const answered = answers.length ? `User has answered your questions: ${text}. ` : "";
+      const status = !dismissed
+        ? "You can now continue with the user's answers in mind."
+        : answers.length
+          ? "The user dismissed the remaining questions without answering."
+          : "The user dismissed the question without answering.";
+      return {
+        content: [{ type: "text", text: answered + status }],
+        details: { answers, dismissed },
+      };
+    },
+  });
+}

package/plugins/pstack/pi/child.ts

@@ -0,0 +1,310 @@
+import { type ChildProcessByStdio, spawn } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
+import type { RpcCommand } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+const STDERR_CAP = 8 * 1024;
+const CLOSE_AFTER_EXIT_MS = 2000;
+
+// What this reader takes from pi's stdout. The stream is pi's, but a line, or
+// the part of one a field comes from, is checked against these before the
+// field is read, and a line that fits none is skipped: one that lacks a field
+// must not end the agent.
+const answerLine = Type.Object({ type: Type.Literal("response"), id: Type.String() });
+const responseSchema = Type.Object({ success: Type.Boolean(), error: Type.Optional(Type.String()) });
+type Answer = Static<typeof responseSchema>;
+const handledPrompt = Type.Object({ command: Type.Literal("prompt"), data: Type.Object({ disposition: Type.Literal("handled") }) });
+const assistantEndLine = Type.Object({
+  type: Type.Literal("message_end"),
+  message: Type.Object({ role: Type.Literal("assistant"), content: Type.Array(Type.Unknown()), stopReason: Type.Optional(Type.Unknown()) }),
+});
+const textPart = Type.Object({ type: Type.Literal("text"), text: Type.String() });
+const failedMessage = Type.Object({ errorMessage: Type.String() });
+const settledLine = Type.Object({ type: Type.Literal("agent_settled") });
+const toolStartLine = Type.Object({ type: Type.Literal("tool_execution_start"), toolCallId: Type.String(), toolName: Type.String(), args: Type.Unknown() });
+const toolEndLine = Type.Object({ type: Type.Literal("tool_execution_end"), toolCallId: Type.String() });
+// Dialogs block the child until the client answers; a notify or status needs none.
+const dialogLine = Type.Object({
+  type: Type.Literal("extension_ui_request"),
+  id: Type.String(),
+  method: Type.Union([Type.Literal("select"), Type.Literal("confirm"), Type.Literal("input"), Type.Literal("editor")]),
+});
+
+export interface ChildExit {
+  exitCode: number | null;
+  // Whether the run reached agent_settled, which is when its work was done.
+  settled: boolean;
+  finalText: string;
+  // "" when the run ended cleanly.
+  errorMessage: string;
+  stderr: string;
+}
+
+// What a running child is doing, last event wins. It lives only in this
+// process's memory: nothing appends it to the session or sends it as a message,
+// and the model sees it only in a list_agents result.
+export interface Activity {
+  // The tool call in flight, or the last one once it ended.
+  tool?: { name: string; args: string; running: boolean };
+  said?: string;
+  // ISO time of the last activity event.
+  at: string;
+}
+
+const TOOL_ARGS_CAP = 80;
+const SAID_CAP = 120;
+
+const cap = (text: string, max: number) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+
+function summarizeArgs(args: unknown): string {
+  const fields = typeof args === "object" && args !== null ? (args as Record<string, unknown>) : {};
+  const named = ["command", "pattern", "path", "file_path"].map((key) => fields[key]).find((value) => typeof value === "string");
+  return cap(oneLine(named ?? JSON.stringify(args) ?? ""), TOOL_ARGS_CAP);
+}
+
+function assistantText(content: unknown[]): string {
+  return content
+    .filter((part) => Value.Check(textPart, part))
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+}
+
+// One `pi --mode rpc` process: the parent's only handle on its stdin and the
+// only reader of its stdout. The prompt goes in as a command, so argv never
+// caps it and a leading @ is never a file. A rejected prompt, or one an
+// extension command consumed, starts no run and so brings no agent_settled;
+// stdin closes at once then, and otherwise at the first agent_settled, after
+// which pi exits on its own.
+export class PiChild {
+  readonly pid: number | undefined;
+  readonly exited: Promise<ChildExit>;
+  private readonly proc: ChildProcessByStdio<Writable, Readable, Readable>;
+  private readonly exitGraceMs: number;
+  private readonly onActivity?: () => void;
+  private readonly pending = new Map<string, (response: Answer | undefined) => void>();
+  private nextId = 0;
+  private open = true;
+  private closeTimer?: NodeJS.Timeout;
+  private settled = false;
+  private finalText = "";
+  private errorMessage = "";
+  private stderr = "";
+  private latest?: Activity;
+  // Tool calls from one message can run in parallel; only the end of the call
+  // shown ends it.
+  private toolCallId?: string;
+
+  constructor(command: string, args: string[], opts: { cwd: string; env?: NodeJS.ProcessEnv; exitGraceMs: number; onActivity?: () => void }, prompt: string) {
+    this.exitGraceMs = opts.exitGraceMs;
+    this.onActivity = opts.onActivity;
+    this.proc = spawn(command, args, { cwd: opts.cwd, env: { ...process.env, ...opts.env }, detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    this.pid = this.proc.pid;
+    this.proc.stdin.on("error", () => {});
+    const stdout = lineSplitter((line) => this.onLine(line));
+    this.proc.stdout.on("data", stdout.write);
+    this.proc.stderr.on("data", (b: Buffer) => {
+      this.stderr = (this.stderr + b.toString("utf8")).slice(-STDERR_CAP);
+    });
+    this.exited = new Promise<ChildExit>((resolve) => {
+      let exitCode: number | null = null;
+      let done = false;
+      const finish = (spawnError?: Error) => {
+        if (done) return;
+        done = true;
+        this.open = false;
+        stdout.end();
+        if (spawnError) this.errorMessage = spawnError.message;
+        for (const settle of this.pending.values()) settle(undefined);
+        this.pending.clear();
+        resolve({ exitCode: spawnError ? null : exitCode, settled: this.settled, finalText: this.finalText, errorMessage: this.errorMessage, stderr: this.stderr });
+      };
+      this.proc.on("error", finish);
+      // A process holding the pipes open after pi exited must not keep the
+      // agent running; it is not signalled, since it is not one this runner
+      // spawned.
+      let pipeTimer: NodeJS.Timeout | undefined;
+      this.proc.on("exit", (code) => {
+        exitCode = code;
+        pipeTimer = setTimeout(() => {
+          this.proc.stdout.destroy();
+          this.proc.stderr.destroy();
+          finish();
+        }, CLOSE_AFTER_EXIT_MS).unref();
+      });
+      this.proc.on("close", (code) => {
+        clearTimeout(pipeTimer);
+        exitCode = code ?? exitCode;
+        finish();
+      });
+    });
+    void this.command({ type: "prompt", message: prompt }).then((response) => {
+      if (!response) return;
+      if (!response.success) this.errorMessage = response.error ?? "pi rejected the prompt";
+      else if (Value.Check(handledPrompt, response)) {
+        this.errorMessage = "pi consumed the prompt as an extension command, so no agent run started. Send the task as plain text.";
+      } else return;
+      this.close();
+    });
+  }
+
+  get activity(): Activity | undefined {
+    return this.latest;
+  }
+
+  private note(change: Pick<Activity, "tool"> | Pick<Activity, "said">): void {
+    this.latest = { ...this.latest, ...change, at: new Date().toISOString() };
+    this.onActivity?.();
+  }
+
+  // Resolves with pi's response, or undefined when stdin is closed or the
+  // process exits first.
+  command(command: RpcCommand): Promise<Answer | undefined> {
+    return new Promise((resolve) => this.send(command, resolve));
+  }
+
+  // Pi answers a steer it reads after settling with "queued" and never runs
+  // it, since it exits on EOF. So a steer was taken into the run only when the
+  // run had not settled as its response was read, which is when `taken` is
+  // decided: the settle can follow in the same chunk of output.
+  steer(message: string): Promise<{ response: Answer | undefined; taken: boolean }> {
+    return new Promise((resolve) =>
+      this.send({ type: "steer", message }, (response) => resolve({ response, taken: response?.success === true && !this.settled })),
+    );
+  }
+
+  private send(command: RpcCommand, onResponse: (response: Answer | undefined) => void): void {
+    if (!this.open) return onResponse(undefined);
+    const id = `c${++this.nextId}`;
+    this.pending.set(id, onResponse);
+    this.proc.stdin.write(`${JSON.stringify({ id, ...command })}\n`);
+  }
+
+  // Pi exits on EOF once idle. One that does not is ended, since nothing else
+  // would end the agent.
+  close(): void {
+    if (!this.endInput()) return;
+    this.closeTimer = setTimeout(() => this.terminate(this.exitGraceMs), this.exitGraceMs).unref();
+  }
+
+  // Ends the run now: stdin closes and one SIGTERM-then-SIGKILL ladder starts,
+  // in place of the one close() would have armed.
+  end(graceMs: number): void {
+    this.endInput();
+    clearTimeout(this.closeTimer);
+    this.terminate(graceMs);
+  }
+
+  private endInput(): boolean {
+    if (!this.open) return false;
+    this.open = false;
+    this.proc.stdin.end();
+    return true;
+  }
+
+  private terminate(graceMs: number): void {
+    if (this.pid) terminateGroup(this.pid, () => this.running, graceMs);
+  }
+
+  // Signals the child's group only while the child itself is alive: once it
+  // has exited the group id may belong to a process this runner never spawned.
+  signal(signal: NodeJS.Signals): void {
+    if (this.pid && this.running) signalGroup(this.pid, signal);
+  }
+
+  private get running(): boolean {
+    return this.proc.exitCode === null && this.proc.signalCode === null;
+  }
+
+  private onLine(line: string): void {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (Value.Check(answerLine, parsed)) {
+      // A response that is not pi's shape still answers its command, as a failure.
+      const malformed = { success: false, error: `malformed response: ${JSON.stringify(parsed).slice(0, 200)}` };
+      this.pending.get(parsed.id)?.(Value.Check(responseSchema, parsed) ? parsed : malformed);
+      this.pending.delete(parsed.id);
+    } else if (Value.Check(assistantEndLine, parsed)) {
+      // A tool-call-only message is normal mid-run and the next text clears
+      // the note; a run that ends on one has no answer, only earlier text.
+      const { message } = parsed;
+      const text = assistantText(message.content);
+      if (text) {
+        this.finalText = text;
+        this.note({ said: cap(oneLine(text.split("\n")[0]), SAID_CAP) });
+      }
+      if (Value.Check(failedMessage, message)) this.errorMessage = message.errorMessage;
+      else this.errorMessage = text ? "" : `(the last assistant message had no text; stop reason: ${String(message.stopReason)})`;
+    } else if (Value.Check(toolStartLine, parsed)) {
+      this.toolCallId = parsed.toolCallId;
+      this.note({ tool: { name: parsed.toolName, args: summarizeArgs(parsed.args), running: true } });
+    } else if (Value.Check(toolEndLine, parsed)) {
+      const tool = this.latest?.tool;
+      if (tool && parsed.toolCallId === this.toolCallId) this.note({ tool: { ...tool, running: false } });
+    } else if (Value.Check(settledLine, parsed)) {
+      this.settled = true;
+      this.close();
+    } else if (Value.Check(dialogLine, parsed)) {
+      this.proc.stdin.write(`${JSON.stringify({ type: "extension_ui_response", id: parsed.id, cancelled: true })}\n`);
+    }
+  }
+}
+
+// Splits pi's stdout into lines on LF only: a Unicode line separator is valid
+// inside a JSON string.
+export function lineSplitter(onLine: (line: string) => void): { write(chunk: Buffer | string): void; end(): void } {
+  const decoder = new StringDecoder("utf8");
+  let buffered = "";
+  const feed = (text: string) => {
+    buffered += text;
+    const lines = buffered.split("\n");
+    buffered = lines.pop() ?? "";
+    for (const line of lines) onLine(line);
+  };
+  return {
+    write: (chunk) => feed(decoder.write(chunk)),
+    end: () => {
+      feed(decoder.end());
+      if (buffered) onLine(buffered);
+    },
+  };
+}
+
+// A process, or with a negative pid its whole group. EPERM means it exists
+// under another user.
+export function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export function signalGroup(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+  } catch {}
+}
+
+// SIGTERM to the group now, SIGKILL if `ours` still holds after the grace
+// period. `ours` guards both signals, since a reused pid is not ours to signal.
+// Resolves when the signal attempt ends, not when the process exits. A restored
+// orphan can retry if either identity check was unavailable during this attempt.
+export function terminateGroup(pid: number, ours: () => boolean, graceMs: number): Promise<void> {
+  if (!ours()) return Promise.resolve();
+  signalGroup(pid, "SIGTERM");
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      if (ours()) signalGroup(pid, "SIGKILL");
+      resolve();
+    }, graceMs).unref();
+  });
+}

package/plugins/pstack/pi/config.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+const PARENT_MODEL_ALIASES = ["inherit-parent", "auto"];
+
+// A parent passes it to each agent it starts, so the agent knows its depth.
+export const DEPTH_FLAG = "pstack-depth";
+// Under agentDir, holds each session's agent sessions and prompts. The worktree
+// audit scans it by this name, so a rename must reach that script too.
+export const PSTACK_STATE_DIR = "pstack";
+// Under agentDir, beside the pstack-models.md sheet, holds the user's agent
+// files. Not Pi's `agents`, which other subagent extensions read with their
+// own frontmatter.
+export const USER_AGENTS_DIR = "pstack-agents";
+
+export interface Settings {
+  pluginRoot: string;
+  modelsFile: string;
+  agentDir: string;
+  pi: { command: string; args: string[] };
+  // Layers below the main session: 0 there, 1 in its agents, and so on.
+  readonly depth: number;
+  killGraceMs: number;
+  // How long a settled child gets to exit after its stdin closes. It covers a
+  // nested child's own shutdown, which stops its agents with killGraceMs each.
+  exitGraceMs: number;
+}
+
+// Pi re-runs itself for children when it can: the same runtime and CLI script,
+// so a child never picks up a different pi from PATH.
+function piInvocation(): Settings["pi"] {
+  const script = process.argv[1];
+  if (script && !script.startsWith("/$bunfs/") && existsSync(script)) {
+    return { command: process.execPath, args: [script] };
+  }
+  const exe = basename(process.execPath).toLowerCase();
+  return /^(node|bun)(\.exe)?$/.test(exe) ? { command: "pi", args: [] } : { command: process.execPath, args: [] };
+}
+
+// readDepth is called on each use: pi parses extension flags after it loads
+// the extension.
+export function defaultSettings(readDepth: () => number, agentDir = process.env.PI_CODING_AGENT_DIR): Settings {
+  const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+  return {
+    pluginRoot,
+    modelsFile: join(pluginRoot, "models.json"),
+    agentDir: agentDir || join(homedir(), ".pi", "agent"),
+    pi: piInvocation(),
+    get depth() {
+      return readDepth();
+    },
+    killGraceMs: 5000,
+    exitGraceMs: 30_000,
+  };
+}
+
+interface Sheet {
+  text: string;
+  hookOff: boolean;
+  // Leaves ask_user_question to another extension: Pi refuses to start when two
+  // extensions register the same tool name.
+  askToolOff: boolean;
+  // Drops agent, send_message, list_agents, stop_agent and /pstack-agents for a
+  // profile that delegates through another extension, such as pi-subagents.
+  agentToolsOff: boolean;
+  piModels: Map<string, string>;
+}
+
+export function parseSheet(text: string): Sheet {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  const piModels = new Map<string, string>();
+  for (const line of lines) {
+    const m = /^pi models:\s*(.*)$/.exec(line.trim());
+    if (!m) continue;
+    for (const pair of m[1].split(",")) {
+      const [alias, id] = pair.split("=").map((s) => s.trim());
+      if (alias && id) piModels.set(alias, id);
+    }
+  }
+  return {
+    text,
+    hookOff: lines.some((l) => l === "session hook: off"),
+    askToolOff: lines.some((l) => l === "pi ask tool: off"),
+    agentToolsOff: lines.some((l) => l === "pi agent tools: off"),
+    piModels,
+  };
+}
+
+export function readSheet(agentDir: string): Sheet | undefined {
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(join(agentDir, "pstack-models.md"));
+  } catch {
+    // An absent or unreadable sheet leaves the defaults in place, as the session hooks do.
+    return undefined;
+  }
+  // Windows PowerShell 5.1's `>` writes UTF-16 LE with a byte-order mark. A
+  // sheet that is not valid UTF-16 LE counts as absent, as in the session hooks.
+  if (bytes[0] !== 0xff || bytes[1] !== 0xfe) return parseSheet(bytes.toString("utf8"));
+  try {
+    // ignoreBOM keeps the byte-order mark, so parseSheet drops exactly one, as for
+    // UTF-8. A Node built without ICU throws here, and the sheet counts as absent.
+    return parseSheet(new TextDecoder("utf-16le", { fatal: true, ignoreBOM: true }).decode(bytes));
+  } catch {
+    return undefined;
+  }
+}
+
+// The parts of models.json the extension reads; the generator checks the rest.
+const modelsConfig = Type.Object({
+  available: Type.Array(Type.String()),
+  efforts: Type.Array(Type.String()),
+  pi: Type.Object({ fallback: Type.String(), models: Type.Record(Type.String(), Type.Record(Type.String(), Type.String())) }),
+});
+
+function readModels(modelsFile: string): Static<typeof modelsConfig> {
+  const text = readFileSync(modelsFile, "utf8");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`${modelsFile} is not valid JSON: ${(e as Error).message}`);
+  }
+  if (!Value.Check(modelsConfig, raw)) throw new Error(`${modelsFile} is not a pstack models file: it needs available[], efforts[] and pi.{fallback, models}.`);
+  return raw;
+}
+
+// A model or effort value that is not valid, unlike a models.json that cannot be read.
+export class InvalidValueError extends Error {}
+
+// Returns the provider/id for --model, or undefined when the child should run
+// on Pi's default because the parent model is unknown.
+export function resolveModel(
+  requested: string | undefined,
+  settings: Settings,
+  sheet: Sheet | undefined,
+  parentModel: string | undefined,
+): string | undefined {
+  if (!requested || PARENT_MODEL_ALIASES.includes(requested)) return parentModel;
+  if (requested.includes("/")) return requested;
+  const models = readModels(settings.modelsFile);
+  if (!models.available.includes(requested)) {
+    const valid = [...models.available, ...PARENT_MODEL_ALIASES, "<provider>/<model-id>"];
+    throw new InvalidValueError(`Unknown model "${requested}". Valid values: ${valid.join(", ")}.`);
+  }
+  // Family names follow the provider the session is signed in to, so a ChatGPT
+  // subscription gets OpenAI models without any configuration.
+  const provider = parentModel?.split("/")[0] ?? "";
+  const table = models.pi.models[Object.hasOwn(models.pi.models, provider) ? provider : models.pi.fallback];
+  const id = sheet?.piModels.get(requested) ?? table[requested];
+  if (!id) {
+    throw new InvalidValueError(`No Pi model mapped for "${requested}": add a "pi models: ${requested}=<provider>/<id>" line to the override sheet.`);
+  }
+  return id;
+}
+
+export const GENERAL_PURPOSE = "general-purpose";
+
+export interface AgentDefinition {
+  // The agent file it was read from; general-purpose has none.
+  file?: string;
+  // When to use it, as the agent tool's type list shows it.
+  description?: string;
+  body: string;
+  model?: string;
+  effort?: string;
+}
+
+// The agent tool's effort parameter: one of models.json's levels.
+export function checkEffort(effort: string, settings: Pick<Settings, "modelsFile">): string {
+  const { efforts } = readModels(settings.modelsFile);
+  if (!efforts.includes(effort)) throw new InvalidValueError(`effort "${effort}" is not one of ${efforts.join(", ")}`);
+  return effort;
+}

package/plugins/pstack/pi/index.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerAgentTools } from "./agent-tools.ts";
+import { AgentRunner } from "./agents.ts";
+import { registerAsk } from "./ask.ts";
+import { DEPTH_FLAG, defaultSettings, readSheet, type Settings } from "./config.ts";
+import { registerOneShot } from "./one-shot.ts";
+import { registerPathSkills } from "./path-skills.ts";
+import { registerPromptSections } from "./prompt.ts";
+import { registerSchedule, Scheduler } from "./schedule.ts";
+
+export function install(pi: ExtensionAPI, settings: Settings): void {
+  const runner = new AgentRunner(pi, settings);
+  const scheduler = new Scheduler();
+  const oneShot = registerOneShot(pi, settings, runner);
+  const sheet = readSheet(settings.agentDir);
+  if (!sheet?.agentToolsOff) registerAgentTools(pi, runner, settings);
+  if (!sheet?.askToolOff) registerAsk(pi, oneShot);
+  registerSchedule(pi, scheduler, oneShot);
+  registerPromptSections(pi, settings);
+  registerPathSkills(pi, settings);
+  // Children run detached, in their own process group, so a parent that exits
+  // without session_shutdown would leave them running: this exit hook signals
+  // them, and each child pi then ends the bash command it has running.
+  const onExit = () => runner.signalAll();
+  process.on("exit", onExit);
+  // Every entry, not the active branch: an agent started on a branch the user
+  // later left is still a process, and its record is the only handle on it.
+  pi.on("session_start", (_event, ctx) => {
+    runner.attachSession(ctx);
+    runner.restore(ctx.sessionManager.getEntries());
+  });
+  pi.on("session_shutdown", async () => {
+    process.off("exit", onExit);
+    oneShot.dispose();
+    scheduler.stopAll();
+    await runner.stopAll();
+  });
+}
+
+export default function pstack(pi: ExtensionAPI): void {
+  pi.registerFlag(DEPTH_FLAG, { type: "string", description: "Layers below the main session; pstack sets it on the agents it starts." });
+  install(pi, defaultSettings(() => Number(pi.getFlag(DEPTH_FLAG)) || 0));
+}