pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/hooks/session-start.ps1

@@ -0,0 +1,105 @@
+param([string] $Runtime)
+$ErrorActionPreference = 'Stop'
+
+function ReadHookFile([string] $name) {
+    [System.IO.File]::ReadAllText((Join-Path $PSScriptRoot $name), [System.Text.Encoding]::UTF8)
+}
+
+# -ccontains, -ceq, and EndsWith(string) compare by culture, which skips
+# zero-width characters, so sheet text is compared ordinally, as sh and awk
+# compare bytes. The runtime argument comes from the hooks files, not the
+# sheet, so its switch and -ceq stay as they are.
+function HasOrdinal([string[]] $list, [string] $item) {
+    $null -ne $list -and [Array]::IndexOf($list, $item) -ge 0
+}
+
+# muse-context.awk prints each file one line at a time, so its last line ends
+# with a newline even when the file's does not.
+function AsLines([string] $text) {
+    if ($text -and -not $text.EndsWith("`n", [System.StringComparison]::Ordinal)) { $text + "`n" } else { $text }
+}
+
+# The sheet's role lines whose entries are all model IDs or aliases, each with
+# an optional known effort, then a usable default effort, in models.json order.
+# These are the lines sheet.awk accepts for muse-context.awk.
+function MuseRoleLines([string[]] $lines) {
+    $models = [System.IO.File]::ReadAllText((Join-Path (Split-Path $PSScriptRoot -Parent) 'models.json'), [System.Text.Encoding]::UTF8) | ConvertFrom-Json
+    $efforts = @($models.efforts)
+    $value = [System.Collections.Generic.Dictionary[string, string]]::new([System.StringComparer]::Ordinal)
+    foreach ($line in $lines) {
+        $colon = $line.IndexOf(':')
+        if ($colon -lt 0 -or $line -cmatch '^[ \t]') { continue }
+        $value[$line.Substring(0, $colon).Trim([char[]]" `t")] = $line.Substring($colon + 1).Trim([char[]]" `t")
+    }
+    foreach ($role in $models.roles.role) {
+        if (-not $value.ContainsKey($role)) { continue }
+        $usable = $true
+        foreach ($raw in $value[$role].Split(',')) {
+            $entry = $raw.Trim([char[]]" `t")
+            if ($entry -cmatch '[ \t]+@([a-z]+)$' -and (HasOrdinal $efforts $Matches[1])) {
+                $entry = $entry.Substring(0, $entry.Length - $Matches[0].Length)
+            }
+            $usable = $usable -and $entry -cmatch '^[a-z0-9][a-z0-9.-]*$'
+        }
+        if ($usable) { "$($role): $($value[$role])" }
+    }
+    $effort = $value['default effort']
+    if (HasOrdinal (@('session') + $efforts) $effort) { "default effort: $effort" }
+}
+
+# Each runtime's hooks file passes its own name, as for session-start.sh.
+switch -CaseSensitive ($Runtime) {
+    'codex' {
+        $sheetRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
+        $sheet = Join-Path $sheetRoot 'pstack-models.md'
+        $context = 'session-start-context.md'
+    }
+    'muse' {
+        # A Linux Muse under WSL can reach powershell.exe through interop, and
+        # the sh hook owns that session. Interop should run this script from a
+        # \\wsl UNC path, and passes MUSE_PLUGIN_ROOT only when WSLENV shares
+        # it; neither signal has been run under WSL.
+        if ($PSScriptRoot -like '\\wsl*' -or $env:MUSE_PLUGIN_ROOT -like '/*') {
+            exit 0
+        }
+        # Muse drops USERPROFILE from the hook environment.
+        $userProfile = if ($env:USERPROFILE) { $env:USERPROFILE } else { [System.Environment]::GetFolderPath('UserProfile') }
+        $sheetRoot = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $userProfile '.config' }
+        $sheet = Join-Path (Join-Path $sheetRoot 'muse') 'pstack-models.md'
+        $context = 'session-start-muse.md'
+    }
+    default {
+        [Console]::Error.WriteLine("session-start.ps1: unknown runtime '$Runtime' (expected codex or muse)")
+        exit 2
+    }
+}
+
+# A missing, unreadable, or undecodable sheet leaves $sheetLines null and the
+# hook on, as session-start.sh does.
+$sheetLines = $null
+if (Test-Path -LiteralPath $sheet -PathType Leaf) {
+    try {
+        $bytes = [System.IO.File]::ReadAllBytes($sheet)
+        # Windows PowerShell 5.1's `>` writes UTF-16 LE with a byte-order mark.
+        # The decoder throws where iconv in read-sheet.sh fails: on an odd byte
+        # count or an unpaired surrogate.
+        $encoding = if ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) { [System.Text.UnicodeEncoding]::new($false, $false, $true) } else { [System.Text.UTF8Encoding]::new($false) }
+        $sheetLines = ($encoding.GetString($bytes) -replace '^\uFEFF', '') -split "`n" | ForEach-Object { $_ -replace "`r$", '' }
+    } catch { }
+}
+if (HasOrdinal $sheetLines 'session hook: off') {
+    exit 0
+}
+
+$output = ReadHookFile $context
+# Muse reads stdout as plain context, so the sheet's checked role lines follow
+# the mandate, as muse-context.awk prints them.
+if ($Runtime -ceq 'muse') {
+    $output = AsLines $output
+    $roleLines = if ($null -eq $sheetLines) { @() } else { @(MuseRoleLines $sheetLines) }
+    if ($roleLines.Count -gt 0) {
+        $output += "`n" + (AsLines (ReadHookFile 'session-start-muse-sheet.md')) + (($roleLines -join "`n") + "`n")
+    }
+}
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::Write($output)

package/plugins/pstack/hooks/session-start.sh

@@ -0,0 +1,95 @@
+#!/bin/sh
+set -eu
+
+# Each runtime's hooks file passes its own name. MiniMax Code runs Claude
+# Code's hooks file, so it is known by the MINIMAX_PLUGIN_ROOT it sets.
+runtime="${1:-}"
+if [ "$runtime" = claude ] && [ -n "${MINIMAX_PLUGIN_ROOT:-}" ]; then
+  runtime=minimax
+fi
+
+# Literal plugin paths, so a static reader of the hooks files can follow them.
+case "$runtime" in
+  agy)
+    # Antigravity starts hooks in the plugin root.
+    sheet="$HOME/.gemini/config/pstack-models.md"
+    reader=./skills/setup-pstack/scripts/read-sheet.sh
+    ;;
+  claude)
+    sheet="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/pstack-models.md"
+    reader="${CLAUDE_PLUGIN_ROOT}/skills/setup-pstack/scripts/read-sheet.sh"
+    ;;
+  minimax)
+    # MiniMax Code withholds MINIMAX_DATA_DIR from hooks and its bash tool.
+    sheet="$HOME/.minimax/pstack-models.md"
+    reader="${MINIMAX_PLUGIN_ROOT}/skills/setup-pstack/scripts/read-sheet.sh"
+    ;;
+  codex)
+    sheet="${CODEX_HOME:-$HOME/.codex}/pstack-models.md"
+    reader="${CLAUDE_PLUGIN_ROOT}/skills/setup-pstack/scripts/read-sheet.sh"
+    ;;
+  copilot)
+    sheet="${COPILOT_HOME:-$HOME/.copilot}/pstack-models.md"
+    reader="${COPILOT_PLUGIN_ROOT}/skills/setup-pstack/scripts/read-sheet.sh"
+    ;;
+  muse)
+    # On Windows the manifest's PowerShell hook owns Muse. `uname -s` names a
+    # Windows sh, busybox-w32's as Windows_NT, and OS covers one without uname.
+    case "$(uname -s 2>/dev/null || true)" in
+      MINGW*|MSYS*|CYGWIN*|Windows_NT) exit 0 ;;
+    esac
+    [ "${OS:-}" != Windows_NT ] || exit 0
+    sheet="${XDG_CONFIG_HOME:-$HOME/.config}/muse/pstack-models.md"
+    reader="${MUSE_PLUGIN_ROOT}/skills/setup-pstack/scripts/read-sheet.sh"
+    ;;
+  *)
+    echo "session-start.sh: unknown runtime '${1:-}' (expected agy, claude, codex, copilot, or muse)" >&2
+    exit 2
+    ;;
+esac
+
+# A sheet that cannot be decoded counts as missing, so injection stays on.
+found=0
+if [ -f "$sheet" ] && [ -r "$sheet" ] && normalized=$(sh "$reader" "$sheet"); then
+  found=1
+else
+  normalized=
+fi
+if printf '%s\n' "$normalized" | grep -qx 'session hook: off'; then
+  [ "$runtime" != agy ] || printf '{}\n'
+  exit 0
+fi
+
+if [ "$runtime" = agy ]; then
+  LC_ALL=C awk -f ./hooks/json.awk -f ./hooks/agy-context.awk ./hooks/session-start-agy.md
+  exit 0
+fi
+
+# GitHub Copilot parses stdout as one JSON object. Its sheet sits outside
+# Copilot's path sandbox, so the hook checks the sheet and adds its role lines
+# to the mandate, and the agent never reads the file. The hooks directory goes
+# through the environment, since awk expands backslash escapes in a -v value.
+if [ "$runtime" = copilot ]; then
+  printf '%s\n' "$normalized" | PSTACK_HOOKS="${COPILOT_PLUGIN_ROOT}/hooks" LC_ALL=C awk -v found="$found" \
+    -f "${COPILOT_PLUGIN_ROOT}/hooks/json.awk" \
+    -f "${COPILOT_PLUGIN_ROOT}/skills/setup-pstack/scripts/sheet.awk" \
+    -f "${COPILOT_PLUGIN_ROOT}/hooks/copilot-context.awk"
+  exit 0
+fi
+
+# Muse reads stdout as plain additional context. Its sheet has no include
+# mechanism, so the hook adds the sheet's known role lines to the Muse
+# mandate itself, rebuilt from their checked values.
+if [ "$runtime" = muse ]; then
+  printf '%s\n' "$normalized" | PSTACK_HOOKS="${MUSE_PLUGIN_ROOT}/hooks" LC_ALL=C awk -v found="$found" \
+    -f "${MUSE_PLUGIN_ROOT}/skills/setup-pstack/scripts/sheet.awk" \
+    -f "${MUSE_PLUGIN_ROOT}/hooks/muse-context.awk"
+  exit 0
+fi
+
+if [ "$runtime" = minimax ]; then
+  cat "${MINIMAX_PLUGIN_ROOT}/hooks/session-start-minimax.md"
+  exit 0
+fi
+
+cat "${CLAUDE_PLUGIN_ROOT}/hooks/session-start-context.md"

package/plugins/pstack/hooks.json

@@ -0,0 +1,10 @@
+{
+  "pstack-routing": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "./hooks/session-start.sh agy"
+      }
+    ]
+  }
+}

package/plugins/pstack/models.json

@@ -0,0 +1,67 @@
+{
+  "tiers": {
+    "default": "opus",
+    "strongest": "fable",
+    "worker": "sonnet",
+    "panel": ["opus", "fable", "sonnet", "haiku"]
+  },
+  "efforts": ["low", "medium", "high", "xhigh", "max"],
+  "defaultEffort": "session",
+  "available": ["opus", "fable", "sonnet", "haiku"],
+  "roles": [
+    { "role": "feature, refactoring", "models": "worker", "skill": "poteto-mode" },
+    { "role": "bug-fix", "models": "default", "skill": "poteto-mode" },
+    { "role": "perf-issue", "models": "default", "skill": "poteto-mode" },
+    { "role": "hillclimb", "models": "default", "skill": "poteto-mode" },
+    { "role": "judgment and prose", "models": "default", "skill": "poteto-mode" },
+    { "role": "strongest judgment", "models": "strongest", "skill": "poteto-mode" },
+    { "role": "how explorer", "models": "default", "skill": "how" },
+    { "role": "how explainer", "models": "default", "skill": "how" },
+    { "role": "why investigators", "models": "default", "skill": "why" },
+    { "role": "why synthesizer", "models": "default", "skill": "why" },
+    { "role": "reflect tooling", "models": "default", "skill": "reflect" },
+    { "role": "reflect judgment, divergent, synthesizer", "models": "default", "skill": "reflect" },
+    { "role": "arena runners", "models": "panel", "skill": "arena" },
+    { "role": "arena cross-judge pool", "models": "panel", "skill": "arena" },
+    { "role": "swarm workers", "models": "default", "skill": "swarm" },
+    { "role": "architect runners", "models": "panel", "skill": "architect" },
+    { "role": "interrogate reviewers", "models": "panel", "skill": "interrogate" },
+    { "role": "thermos reviewers", "models": "default", "skill": "thermos" },
+    { "role": "no-comments reviewer", "models": "default", "skill": "no-comments" }
+  ],
+  "codex": {
+    "default": "gpt-6.1-sol",
+    "strongest": "gpt-6-astra",
+    "worker": "gpt-6.1-sol",
+    "panel": ["gpt-6-astra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna"]
+  },
+  "pi": {
+    "fallback": "anthropic",
+    "models": {
+      "anthropic": {
+        "opus": "anthropic/claude-opus-5-5",
+        "fable": "anthropic/claude-fable-5-1",
+        "sonnet": "anthropic/claude-sonnet-5-5",
+        "haiku": "anthropic/claude-haiku-5-5"
+      },
+      "openai": {
+        "opus": "openai/gpt-6.1-sol",
+        "fable": "openai/gpt-6-astra",
+        "sonnet": "openai/gpt-6.1-sol",
+        "haiku": "openai/gpt-6-luna"
+      },
+      "openai-codex": {
+        "opus": "openai-codex/gpt-6.1-sol",
+        "fable": "openai-codex/gpt-6-astra",
+        "sonnet": "openai-codex/gpt-6.1-sol",
+        "haiku": "openai-codex/gpt-6-luna"
+      }
+    }
+  },
+  "muse": {
+    "default": "muse-wonder-1.0",
+    "strongest": "muse-wonder-full-1.0",
+    "worker": "muse-spark-1.3",
+    "panel": ["muse-wonder-full-1.0", "muse-wonder-1.0", "muse-spark-1.3"]
+  }
+}

package/plugins/pstack/omp/index.mjs

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const skills = join(root, "skills");
+const mapping = join(root, "skills", "poteto-mode", "references", "omp-tools.md");
+const mandate = readFileSync(join(root, "hooks", "session-start-context.md"), "utf8");
+const marker = "[pstack OMP instructions]";
+
+function instructions(routed) {
+  const adapter = `${marker}\nBefore following a pstack skill, read ${JSON.stringify(mapping)} for OMP tool and model mappings. Resolve every pstack:<name> skill in the following instructions by reading the installed plugin file at ${JSON.stringify(join(skills, "<name>", "SKILL.md"))}, substituting the named skill. For example, read ${JSON.stringify(join(skills, "poteto-mode", "SKILL.md"))} for pstack:poteto-mode. Do not resolve these names through a bare skill name, which can select a different installation.`;
+  return routed ? `${adapter}\n${mandate}` : adapter;
+}
+
+function routingOff() {
+  try {
+    const bytes = readFileSync(join(homedir(), ".omp", "pstack-models.md"));
+    const text = bytes[0] === 0xff && bytes[1] === 0xfe
+      ? new TextDecoder("utf-16le", { fatal: true }).decode(bytes)
+      : bytes.toString("utf8").replace(/^\uFEFF/, "");
+    return text.split(/\r?\n/).includes("session hook: off");
+  } catch {
+    return false;
+  }
+}
+
+export default function pstack(omp) {
+  omp.on("before_agent_start", (event, ctx) => {
+    if (event.systemPrompt.some((section) => section.includes(marker))) return;
+    return { systemPrompt: [...event.systemPrompt, instructions(ctx.agent.kind === "main" && !routingOff())] };
+  });
+}

package/plugins/pstack/opencode/index.js

@@ -0,0 +1,49 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const skillsDir = join(root, "skills");
+
+function readSkills() {
+  return readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => {
+    const path = join(skillsDir, entry.name, "SKILL.md");
+    const text = readFileSync(path, "utf8");
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match) throw new Error(`Missing skill frontmatter: ${path}`);
+    const metadata = Bun.YAML.parse(match[1]);
+    return { id: `pstack-${entry.name}`, name: metadata.name, description: metadata.description, path, content: text.slice(match[0].length) };
+  });
+}
+
+function hookEnabled() {
+  const config = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  try {
+    const bytes = readFileSync(join(config, "opencode", "pstack-models.md"));
+    const text = bytes[0] === 0xff && bytes[1] === 0xfe
+      ? new TextDecoder("utf-16le", { fatal: true, ignoreBOM: true }).decode(bytes)
+      : bytes.toString("utf8");
+    return !text.replace(/^\uFEFF/, "").split(/\r?\n/).includes("session hook: off");
+  } catch {
+    return true;
+  }
+}
+
+export default {
+  id: "pstack",
+  async setup(ctx) {
+    const skills = readSkills();
+    const mandate = readFileSync(join(root, "hooks", "session-start-opencode.md"), "utf8");
+    await ctx.skill.transform((editor) => {
+      for (const skill of skills) if (!editor.get(skill.id)) editor.add(skill);
+    });
+    await ctx.session.hook("context", async (event) => {
+      const session = await ctx.session.get({ sessionID: event.sessionID });
+      if (session.parentID || !hookEnabled()) return;
+      const installed = new Map((await ctx.skill.list()).data.map((skill) => [skill.id, skill.path]));
+      if (skills.some((skill) => installed.get(skill.id) !== skill.path)) return;
+      event.system.push({ type: "text", text: mandate });
+    });
+  },
+};

package/plugins/pstack/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "pstack",
+  "version": "0.9.133",
+  "private": true,
+  "omp": {
+    "extensions": ["./omp/index.mjs"]
+  }
+}

package/plugins/pstack/pi/agent-files.ts

@@ -0,0 +1,117 @@
+// The agent types the agent tool offers, read from agent files. Kept out of
+// config.ts, which tools and tests import for its settings, so that only the
+// extension's agent code loads Pi's package for its YAML reader.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+import { type AgentDefinition, GENERAL_PURPOSE, type Settings, USER_AGENTS_DIR } from "./config.ts";
+
+// Claude Code 2.1.310's retry for frontmatter that is not YAML: quote each
+// unquoted top-level value that holds YAML syntax, so `description: Use for
+// a: b` reads as text, and turn leading tabs into spaces. Claude Code also
+// keeps a `[...]` value that parses as a list; the extension reads no list
+// field from a file that needs the retry, so that case is left out.
+function quoteAsText(yaml: string): string {
+  const lines = yaml.split("\n").map((line) => {
+    const kv = /^([a-zA-Z_-]+):\s+(\S.*)$/.exec(line);
+    if (!kv) return line;
+    const [, name, value] = kv;
+    const quoted = (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"));
+    if (quoted || !/[{}[\]*&#!|>%@`]|: /.test(value)) return line;
+    return `${name}: "${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  });
+  return lines.join("\n").replace(/^\t+/gm, (tabs) => "  ".repeat(tabs.length));
+}
+
+// Claude Code's YAML reader, Bun's, keeps the last value of a repeated
+// top-level field, where Pi's rejects the field. Drops each earlier entry with
+// every line up to the next field, a list written at column 0 included.
+function lastOfEachKey(yaml: string): string {
+  const lines = yaml.split("\n");
+  const keyOf = (line: string) => /^([^\s#][^:]*):(?:\s|$)/.exec(line)?.[1];
+  const last = new Map(lines.map((line, i) => [keyOf(line), i]));
+  let dropping = false;
+  return lines
+    .filter((line, i) => {
+      const name = keyOf(line);
+      if (name !== undefined) dropping = last.get(name) !== i;
+      return !dropping;
+    })
+    .join("\n");
+}
+
+// Pi's YAML reader, then Claude Code's: first with a repeated field's last
+// value, then with its retry. Frontmatter that fails all three throws.
+export function frontmatter(text: string): { fields: Record<string, unknown>; body: string } {
+  let parsed: ReturnType<typeof parseFrontmatter>;
+  try {
+    parsed = parseFrontmatter(text);
+  } catch {
+    // parseFrontmatter only throws on a file that opens with ---, after any byte-order mark, which trimStart drops.
+    const lf = text.trimStart().replace(/\r\n?/g, "\n");
+    const rewritten = (rewrite: (yaml: string) => string) =>
+      parseFrontmatter(lf.replace(/^(---\n)([\s\S]*?)(\n---)/, (_, open: string, yaml: string, close: string) => open + rewrite(yaml) + close));
+    try {
+      parsed = rewritten(lastOfEachKey);
+    } catch {
+      parsed = rewritten((yaml) => quoteAsText(lastOfEachKey(yaml)));
+    }
+  }
+  return { fields: parsed.frontmatter, body: parsed.body.trim() };
+}
+
+// A field as text, trimmed as Claude Code reads it; an empty or missing one is undefined.
+function scalar(value: unknown): string | undefined {
+  return value == null ? undefined : String(value).trim() || undefined;
+}
+
+function parseAgentFile(file: string, text: string): AgentDefinition {
+  const { fields, body } = frontmatter(text);
+  // Claude Code's `model: inherit` runs the agent on the parent's model, as no model does.
+  const model = scalar(fields.model);
+  return { file, description: scalar(fields.description), body, model: model !== "inherit" ? model : undefined, effort: scalar(fields.effort) };
+}
+
+// Claude Code registers each plugin agent file as pstack:<file name>, beside
+// the built-in general-purpose type, which has no agent file, and a user agent
+// file under its bare name. A user file only adds a type, never replaces one.
+export function loadAgentTypes(settings: Pick<Settings, "pluginRoot" | "agentDir">): Map<string, AgentDefinition> {
+  // The built-in type's description is Claude Code's own.
+  const types = new Map<string, AgentDefinition>([
+    [GENERAL_PURPOSE, { body: "", description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you." }],
+  ]);
+  const dir = join(settings.pluginRoot, "agents");
+  if (existsSync(dir)) {
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".md")).sort()) {
+      const type = `pstack:${basename(file, ".md")}`;
+      const path = join(dir, file);
+      types.set(type, parseAgentFile(path, readFileSync(path, "utf8")));
+    }
+  }
+  for (const [type, def] of userAgentFiles(join(settings.agentDir, USER_AGENTS_DIR))) {
+    if (!types.has(type)) types.set(type, def);
+  }
+  return types;
+}
+
+// Each readable .md file in the user's folder, by bare name. A hidden file, such
+// as a macOS ._ sidecar, a name with a colon, which Claude Code keeps for plugin
+// agents, an entry that is not a readable file, and a folder that cannot be
+// listed are skipped, so the user's folder never breaks the plugin's agent types.
+function userAgentFiles(dir: string): [string, AgentDefinition][] {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith(".") && !f.includes(":")).sort();
+  } catch {
+    return [];
+  }
+  return files.flatMap((file): [string, AgentDefinition][] => {
+    const path = join(dir, file);
+    try {
+      return statSync(path).isFile() ? [[basename(file, ".md"), parseAgentFile(path, readFileSync(path, "utf8"))]] : [];
+    } catch {
+      return [];
+    }
+  });
+}

package/plugins/pstack/pi/agent-text.ts

@@ -0,0 +1,99 @@
+// What the model reads about an agent: tool results, completion notices, and
+// the cap on text that stays inline. Pure functions of the persisted record
+// and the path of the child's transcript and its live activity, which the
+// caller looks up.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { AgentRecord, EndedRecord } from "./agents.ts";
+import type { Activity } from "./child.ts";
+
+const NOTICE_TYPE = "pstack-agent";
+export const OUTPUT_CAP_BYTES = 50 * 1024;
+
+export function truncateUtf8(text: string, cap: number): string {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= cap) return text;
+  let end = cap;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return buf.subarray(0, end).toString("utf8");
+}
+
+function header({ agent, ...record }: EndedRecord, transcript: string | undefined): string {
+  const lines = [`agentId: ${agent.id}`, `description: ${agent.description}`, `status: ${record.status}`, `exit code: ${record.exitCode}`];
+  if (agent.worktree) {
+    const state = record.worktreeKept === false ? "no changes; removed" : `branch ${agent.worktree.branch}`;
+    lines.push(`worktree: ${agent.worktree.path} (${state})`);
+  }
+  if (transcript) lines.push(`transcript: ${transcript}`);
+  return lines.join("\n");
+}
+
+// The record's text is already cut to the cap, with the full copy on disk.
+function report(record: EndedRecord): string {
+  if (!record.outputFile) return record.finalText;
+  return `${record.finalText}\n\n[Output truncated at ${OUTPUT_CAP_BYTES / 1024} KB. Full output: ${record.outputFile}]`;
+}
+
+export function resultText(record: EndedRecord, transcript: string | undefined): string {
+  return `${header(record, transcript)}\n\n${report(record)}`;
+}
+
+type Lookups = {
+  transcriptOf: (agent: AgentRecord["agent"]) => string | undefined;
+  activityOf: (agent: AgentRecord["agent"]) => Activity | undefined;
+};
+
+export function listing(records: AgentRecord[], { transcriptOf, activityOf }: Lookups): object[] {
+  return records.map(({ agent, ...r }) => ({
+    id: agent.id,
+    description: agent.description,
+    subagent_type: agent.subagentType,
+    model: agent.model ?? "(pi default)",
+    status: r.status,
+    pid: r.pid,
+    startedAt: agent.startedAt,
+    endedAt: r.status === "running" ? undefined : r.endedAt,
+    worktree: agent.worktree?.path,
+    sessionFile: transcriptOf(agent),
+    activity: r.status === "running" ? activityOf(agent) : undefined,
+  }));
+}
+
+const toolLine = ({ name, args }: NonNullable<Activity["tool"]>) => (args ? `${name}: ${args}` : name);
+
+// The footer line: how many run, then the most recently active one.
+export function statusText(running: { id: string; at: string; activity?: Activity }[]): string | undefined {
+  if (!running.length) return undefined;
+  const latest = running.reduce((a, b) => (b.at > a.at ? b : a));
+  const { tool, said } = latest.activity ?? {};
+  const doing = tool?.running ? toolLine(tool) : (said ?? (tool && toolLine(tool)));
+  return `pstack: ${running.length} running${doing ? ` · ${latest.id.slice(0, 8)} ${doing}` : ""}`;
+}
+
+const shellPath = (path: string) => /^[A-Za-z0-9_./-]+$/.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+
+// What /pstack-agents shows the user: one block per agent.
+export function agentsReport(records: AgentRecord[], { transcriptOf, activityOf }: Lookups): string {
+  if (!records.length) return "No pstack agents in this session.";
+  return records
+    .map(({ agent, status }) => {
+      const lines = [`${agent.id} ${status}: ${agent.description}`];
+      const activity = status === "running" ? activityOf(agent) : undefined;
+      if (activity?.tool) lines.push(`${activity.tool.running ? "now" : "last"}: ${toolLine(activity.tool)}`);
+      if (activity?.said) lines.push(`said: ${activity.said}`);
+      const transcript = transcriptOf(agent);
+      if (transcript) lines.push(`transcript: ${transcript}`, `read it: ${status === "running" ? "tail -f" : "pi --export"} ${shellPath(transcript)}`);
+      else lines.push("transcript: not written yet");
+      return lines.join("\n");
+    })
+    .join("\n\n");
+}
+
+export function noticeOf(record: EndedRecord, transcript: string | undefined): Parameters<ExtensionAPI["sendMessage"]>[0] {
+  return {
+    customType: NOTICE_TYPE,
+    content: `pstack agent finished.\n${header(record, transcript)}${record.outputFile ? `\nfull output: ${record.outputFile}` : ""}\n\n${report(record)}`,
+    display: true,
+    details: { agentId: record.agent.id, status: record.status, exitCode: record.exitCode, outputFile: record.outputFile },
+  };
+}