@clanker-code/pi-subagents 0.10.5

package/src/invocation-config.ts

@@ -0,0 +1,42 @@
+import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+
+interface AgentInvocationParams {
+  model?: string;
+  thinking?: string;
+  max_turns?: number;
+  inherit_context?: boolean;
+  isolated?: boolean;
+  isolation?: IsolationMode;
+}
+
+export function resolveAgentInvocationConfig(
+  agentConfig: AgentConfig | undefined,
+  params: AgentInvocationParams,
+): {
+  modelInput?: string;
+  modelFromParams: boolean;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  inheritContext: boolean;
+  isolated: boolean;
+  isolation?: IsolationMode;
+} {
+  return {
+    modelInput: agentConfig?.model ?? params.model,
+    modelFromParams: agentConfig?.model == null && params.model != null,
+    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+    inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+    isolated: agentConfig?.isolated ?? params.isolated ?? false,
+    isolation: agentConfig?.isolation ?? params.isolation,
+  };
+}
+
+/**
+ * Resolve the join mode for a spawned agent. This fork runs every agent in the
+ * background, so the join mode is always the configured default (no foreground
+ * case to suppress it).
+ */
+export function resolveJoinMode(defaultJoinMode: JoinMode): JoinMode {
+  return defaultJoinMode;
+}

package/src/memory.ts

@@ -0,0 +1,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → ~/.pi/agent-memory/{agent-name}/
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ */
+
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, } from "node:path";
+import type { MemoryScope } from "./types.js";
+
+/** Maximum lines to read from MEMORY.md */
+const MAX_MEMORY_LINES = 200;
+
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name: string): boolean {
+  if (!name || name.length > 128) return true;
+  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath: string): boolean {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  if (isSymlink(filePath)) return undefined;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string {
+  if (isUnsafeName(agentName)) {
+    throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
+  }
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".pi", "agent-memory", agentName);
+    case "project":
+      return join(cwd, ".pi", "agent-memory", agentName);
+    case "local":
+      return join(cwd, ".pi", "agent-memory-local", agentName);
+  }
+}
+
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export function ensureMemoryDir(memoryDir: string): void {
+  // If the directory already exists, verify it's not a symlink
+  if (existsSync(memoryDir)) {
+    if (isSymlink(memoryDir)) {
+      throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+    }
+    return;
+  }
+  mkdirSync(memoryDir, { recursive: true });
+}
+
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export function readMemoryIndex(memoryDir: string): string | undefined {
+  // Reject symlinked memory directories
+  if (isSymlink(memoryDir)) return undefined;
+
+  const memoryFile = join(memoryDir, "MEMORY.md");
+  const content = safeReadFile(memoryFile);
+  if (content === undefined) return undefined;
+
+  const lines = content.split("\n");
+  if (lines.length > MAX_MEMORY_LINES) {
+    return lines.slice(0, MAX_MEMORY_LINES).join("\n") + "\n... (truncated at 200 lines)";
+  }
+  return content;
+}
+
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  // Create the memory directory so the agent can immediately write to it
+  ensureMemoryDir(memoryDir);
+
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory
+
+You have a persistent memory directory at: ${memoryDir}/
+Memory scope: ${scope}
+
+This memory persists across sessions. Use it to build up knowledge over time.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo MEMORY.md exists yet. Create one at ${join(memoryDir, "MEMORY.md")} to start building persistent memory.`;
+
+  const instructions = `
+
+## Memory Instructions
+- MEMORY.md is an index file — keep it concise (under 200 lines). Lines after 200 are truncated.
+- Store detailed memories in separate files within ${memoryDir}/ and link to them from MEMORY.md.
+- Each memory file should use this frontmatter format:
+  \`\`\`markdown
+  ---
+  name: <memory name>
+  description: <one-line description>
+  type: <user|feedback|project|reference>
+  ---
+  <memory content>
+  \`\`\`
+- Update or remove memories that become outdated. Check for existing memories before creating duplicates.
+- You have Read, Write, and Edit tools available for managing memory files.`;
+
+  return header + memoryContent + instructions;
+}
+
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory (read-only)
+
+Memory scope: ${scope}
+You have read-only access to memory. You can reference existing memories but cannot create or modify them.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo memory is available yet. Other agents or sessions with write access can create memories for you to consume.`;
+
+  return header + memoryContent;
+}

package/src/model-resolver.ts

@@ -0,0 +1,81 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+
+export interface ModelEntry {
+  id: string;
+  name: string;
+  provider: string;
+}
+
+export interface ModelRegistry {
+  find(provider: string, modelId: string): any;
+  getAll(): any[];
+  getAvailable?(): any[];
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(
+  input: string,
+  registry: ModelRegistry,
+): any | string {
+  // Available models (those with auth configured)
+  const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
+
+  // 1. Exact match: "provider/modelId" — only if available (has auth)
+  const slashIdx = input.indexOf("/");
+  if (slashIdx !== -1) {
+    const provider = input.slice(0, slashIdx);
+    const modelId = input.slice(slashIdx + 1);
+    if (availableSet.has(input.toLowerCase())) {
+      const found = registry.find(provider, modelId);
+      if (found) return found;
+    }
+  }
+
+  // 2. Fuzzy match against available models
+  const query = input.toLowerCase();
+
+  // Score each model: prefer exact id match > id contains > name contains > provider+id contains
+  let bestMatch: ModelEntry | undefined;
+  let bestScore = 0;
+
+  for (const m of all) {
+    const id = m.id.toLowerCase();
+    const name = m.name.toLowerCase();
+    const full = `${m.provider}/${m.id}`.toLowerCase();
+
+    let score = 0;
+    if (id === query || full === query) {
+      score = 100; // exact
+    } else if (id.includes(query) || full.includes(query)) {
+      score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+    } else if (name.includes(query)) {
+      score = 40 + (query.length / name.length) * 20;
+    } else if (query.split(/[\s\-/]+/).every(part => id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))) {
+      score = 20; // all parts present somewhere
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = m;
+    }
+  }
+
+  if (bestMatch && bestScore >= 20) {
+    const found = registry.find(bestMatch.provider, bestMatch.id);
+    if (found) return found;
+  }
+
+  // 3. No match — list available models
+  const modelList = all
+    .map(m => `  ${m.provider}/${m.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}

package/src/notifications.ts

@@ -0,0 +1,120 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { getStatusNote } from "./status-note.js";
+import type { AgentRecord, NotificationDetails } from "./types.js";
+import type { AgentActivity } from "./ui/agent-widget.js";
+import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
+import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
+
+function getStatusLabel(status: string, error?: string): string {
+  switch (status) {
+    case "error": return `Error: ${error ?? "unknown"}`;
+    case "aborted": return "Aborted (max turns exceeded)";
+    case "steered": return "Wrapped up (turn limit)";
+    case "stopped": return "Stopped";
+    default: return "Done";
+  }
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function formatTaskNotification(record: AgentRecord, resultMaxLen: number): string {
+  const status = getStatusLabel(record.status, record.error);
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const contextPercent = getSessionContextPercent(record.session);
+  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
+
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen
+      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      : record.result
+    : "No output.";
+  const fullOutputInstruction = record.outputFile
+    ? `Read the full output/log with get_subagent_result for agent ${record.id}, or inspect the transcript file: ${record.outputFile}`
+    : `Read the full output/log with get_subagent_result for agent ${record.id}.`;
+
+  return [
+    `<task-notification>`,
+    `<task-id>${record.id}</task-id>`,
+    record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
+    record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status)}</summary>`,
+    `<result>${escapeXml(resultPreview)}</result>`,
+    `<full-output>${escapeXml(fullOutputInstruction)}</full-output>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+    `</task-notification>`,
+  ].filter(Boolean).join("\n");
+}
+
+export function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, activity?: AgentActivity): NotificationDetails {
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    turnCount: activity?.turnCount ?? 0,
+    maxTurns: activity?.maxTurns,
+    totalTokens,
+    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    outputFile: record.outputFile,
+    error: record.error,
+    resultPreview: record.result
+      ? record.result.length > resultMaxLen
+        ? record.result.slice(0, resultMaxLen) + "…"
+        : record.result
+      : "No output.",
+  };
+}
+
+export function registerSubagentNotificationRenderer(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer<NotificationDetails>(
+    "subagent-notification",
+    (message, { expanded }, theme) => {
+      const d = message.details;
+      if (!d) return undefined;
+
+      function renderOne(d: NotificationDetails): string {
+        const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
+        const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+        const statusText = isError ? d.status
+          : d.status === "steered" ? "completed (steered)"
+          : "completed";
+
+        let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+        const parts: string[] = [];
+        if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
+        if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+        if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+        if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+        if (parts.length) {
+          line += "\n  " + parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+        }
+
+        if (expanded) {
+          const lines = d.resultPreview.split("\n").slice(0, 30);
+          for (const resultLine of lines) line += "\n" + theme.fg("dim", `  ${resultLine}`);
+        } else {
+          const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
+          line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+        }
+
+        const fullOutputHint = d.outputFile
+          ? `full output: get_subagent_result ${d.id} or transcript: ${d.outputFile}`
+          : `full output: get_subagent_result ${d.id}`;
+        line += "\n  " + theme.fg("muted", fullOutputHint);
+
+        return line;
+      }
+
+      const all = [d, ...(d.others ?? [])];
+      return new Text(all.map(renderOne).join("\n"), 0, 0);
+    },
+  );
+}

package/src/output-file.ts

@@ -0,0 +1,96 @@
+/**
+ * output-file.ts — Streaming JSONL output file for agent transcripts.
+ *
+ * Creates a per-agent output file that streams conversation turns as JSONL,
+ * matching Claude Code's task output file format.
+ */
+
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd: string): string {
+  return cwd
+    .replace(/[/\\]/g, "-")        // both separators → dash
+    .replace(/^[A-Za-z]:-/, "")    // strip Windows drive prefix ("C:-")
+    .replace(/^-+/, "");           // strip leading dashes (POSIX root, UNC)
+}
+
+/** Create the output file path, ensuring the directory exists.
+ *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
+export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
+  const encoded = encodeCwd(cwd);
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  // chmod is a no-op on Windows and throws on some Windows filesystems.
+  // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+  try {
+    chmodSync(root, 0o700);
+  } catch (err) {
+    if (process.platform !== "win32") throw err;
+  }
+  const dir = join(root, encoded, sessionId, "tasks");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${agentId}.output`);
+}
+
+/** Write the initial user prompt entry. */
+export function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
+  const entry = {
+    isSidechain: true,
+    agentId,
+    type: "user",
+    message: { role: "user", content: prompt },
+    timestamp: new Date().toISOString(),
+    cwd,
+  };
+  writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+}
+
+/**
+ * Subscribe to session events and flush new messages to the output file on each turn_end.
+ * Returns a cleanup function that does a final flush and unsubscribes.
+ */
+export function streamToOutputFile(
+  session: AgentSession,
+  path: string,
+  agentId: string,
+  cwd: string,
+): () => void {
+  let writtenCount = 1; // initial user prompt already written
+
+  const flush = () => {
+    const messages = session.messages;
+    while (writtenCount < messages.length) {
+      const msg = messages[writtenCount];
+      const entry = {
+        isSidechain: true,
+        agentId,
+        type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
+        message: msg,
+        timestamp: new Date().toISOString(),
+        cwd,
+      };
+      try {
+        appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+      } catch { /* ignore write errors */ }
+      writtenCount++;
+    }
+  };
+
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "turn_end") flush();
+  });
+
+  return () => {
+    flush();
+    unsubscribe();
+  };
+}

package/src/peek.ts

@@ -0,0 +1,155 @@
+/**
+ * peek.ts — Lightweight tail/filter view of an agent's result or streaming
+ * output file for `get_subagent_result`'s `peek` parameter.
+ *
+ * Design:
+ * - Source precedence: streaming output file (best for running agents) → record
+ *   result (finished agents) → "no output yet".
+ * - The output file is JSONL (one entry per message). We extract human-readable
+ *   text lines (assistant text + tool-result text) so a peek shows useful
+ *   progress, not raw JSON.
+ * - Semantics: filter-then-tail. If `regex` is given, only matching source lines
+ *   are kept; then `after` (return all lines past an index) or `lines` (last N)
+ *   is applied. Line numbers always refer to the FULL source so callers can use
+ *   `after` for incremental updates without missing anything.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import type { AgentRecord } from "./types.js";
+
+export interface PeekOptions {
+  /** Number of trailing lines to return. Default 20. Minimum 1. */
+  lines?: number;
+  /** Optional regex filter applied to each source line (filter-then-tail). */
+  regex?: string;
+  /** Return all source lines after this 1-based line number (matches the [N] prefixes in peek output). Use the last line number you saw to fetch only new lines. Overrides `lines`. */
+  after?: number;
+}
+
+export interface PeekResult {
+  /** The formatted peek text (with line-number prefixes and a header). */
+  text: string;
+  /** Number of source lines available (before filtering). */
+  totalLines: number;
+  /** Whether the source was the output file (live) or the result. */
+  source: "outputFile" | "result";
+}
+
+/** Default number of tail lines when neither `after` nor `lines` is given. */
+const DEFAULT_LINES = 20;
+
+/**
+ * Produce a peek view of an agent's output. Returns null when there is no
+ * source content at all (the caller renders a "no output yet" message).
+ */
+export function peekAgentOutput(record: AgentRecord, opts: PeekOptions = {}): PeekResult | null {
+  const lines = readSourceLines(record);
+  if (lines.length === 0) return null;
+
+  const regex = opts.regex ? compileRegex(opts.regex) : undefined;
+  const after = typeof opts.after === "number" ? opts.after : -1;
+  const tail = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+
+  // Index each source line with its original position (1-based for display).
+  const indexed = lines.map((text, i) => ({ no: i + 1, text }));
+
+  // Filter-then-select.
+  const filtered = regex ? indexed.filter((l) => regex.test(l.text)) : indexed;
+  const selected =
+    after >= 0
+      ? filtered.filter((l) => l.no > after)
+      : filtered.slice(-tail);
+
+  const totalLines = lines.length;
+  const isRunning = record.status === "running" || record.status === "queued";
+  const source: PeekResult["source"] =
+    isRunning && record.outputFile && existsSync(record.outputFile) ? "outputFile" : "result";
+
+  const header = buildHeader(opts, selected.length, totalLines, source);
+  const body = selected.map((l) => `[${l.no}] ${l.text}`).join("\n");
+
+  return { text: `${header}\n\n${body}`, totalLines, source };
+}
+
+/** Read the most useful text lines from the agent's output. */
+function readSourceLines(record: AgentRecord): string[] {
+  const isRunning = record.status === "running" || record.status === "queued";
+  const outputFileLines =
+    record.outputFile && existsSync(record.outputFile) ? parseOutputFileLines(record.outputFile) : [];
+
+  // While running, the live output file is the only source of progress.
+  if (isRunning && outputFileLines.length > 0) return outputFileLines;
+
+  // Finished (or no live file): prefer the clean result text.
+  if (record.result?.trim()) {
+    return record.result.split("\n");
+  }
+
+  // Last resort: the output file (e.g. agent errored before producing a result).
+  return outputFileLines;
+}
+
+/**
+ * Parse the JSONL output file and extract human-readable text lines.
+ * Each entry has `{ type, message: { role, content } }`. We pull assistant text
+ * and tool-result text so a peek reflects actual progress.
+ */
+function parseOutputFileLines(path: string): string[] {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: any;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const content = entry?.message?.content;
+    if (!Array.isArray(content)) {
+      // Some entries may carry a plain string content.
+      if (typeof content === "string" && content.trim()) out.push(content.trim());
+      continue;
+    }
+    for (const block of content) {
+      if (block?.type === "text" && typeof block.text === "string" && block.text.trim()) {
+        out.push(block.text.trimEnd());
+      }
+    }
+  }
+  return out;
+}
+
+function compileRegex(pattern: string): RegExp {
+  // Anchor-free; case-sensitive by default. Invalid patterns fall back to a
+  // substring literal match so a bad regex never throws into the tool result.
+  try {
+    return new RegExp(pattern);
+  } catch {
+    return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  }
+}
+
+function buildHeader(
+  opts: PeekOptions,
+  shown: number,
+  total: number,
+  source: PeekResult["source"],
+): string {
+  const parts: string[] = [];
+  if (typeof opts.after === "number") {
+    parts.push(`after line number ${opts.after}`);
+  } else {
+    const n = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+    parts.push(`last ${n} lines`);
+  }
+  if (opts.regex) parts.push(`filtered by regex /${opts.regex}/`);
+  parts.push(`of ${total} total (${source === "outputFile" ? "live output file" : "result"})`);
+  return `Showing ${shown} ${parts.join(", ")}. Line numbers index the full source.`;
+}