xtrm-tools 0.5.0

package/config/pi/extensions/bg-process/index.ts

@@ -0,0 +1,230 @@
+/**
+ * oh-pi Background Process Extension
+ *
+ * 任何 bash 命令超时未完成时，自动送到后台执行。
+ * 进程完成后自动通过 sendMessage 通知 LLM，无需轮询。
+ * 提供 bg_status 工具让 LLM 查看/停止后台进程。
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { spawn, execSync } from "node:child_process";
+import { writeFileSync, readFileSync, appendFileSync, existsSync } from "node:fs";
+
+/** 超时阈值（毫秒），超过此时间自动后台化 */
+const BG_TIMEOUT_MS = 10_000;
+
+interface BgProcess {
+  pid: number;
+  command: string;
+  logFile: string;
+  startedAt: number;
+  finished: boolean;
+  exitCode: number | null;
+}
+
+export default function (pi: ExtensionAPI) {
+  const bgProcesses = new Map<number, BgProcess>();
+
+  // 覆盖内置 bash 工具
+  pi.registerTool({
+    name: "bash",
+    label: "Bash",
+    description: `Execute a bash command. Output is truncated to 2000 lines or 50KB. If a command runs longer than ${BG_TIMEOUT_MS / 1000}s, it is automatically backgrounded and you get the PID + log file path. Use the bg_status tool to check on backgrounded processes.`,
+    parameters: Type.Object({
+      command: Type.String({ description: "Bash command to execute" }),
+      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
+    }),
+    async execute(toolCallId, params, signal) {
+      const { command } = params;
+      const userTimeout = params.timeout ? params.timeout * 1000 : undefined;
+      const effectiveTimeout = userTimeout ?? BG_TIMEOUT_MS;
+
+      return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let backgrounded = false;
+
+        const child = spawn("bash", ["-c", command], {
+          cwd: process.cwd(),
+          env: { ...process.env },
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+
+        child.stdout?.on("data", (d: Buffer) => {
+          const chunk = d.toString();
+          stdout += chunk;
+          // 后台化后追加写入日志
+          if (backgrounded) {
+            try { appendFileSync(bgProcesses.get(child.pid!)?.logFile ?? "", chunk); } catch {}
+          }
+        });
+        child.stderr?.on("data", (d: Buffer) => {
+          const chunk = d.toString();
+          stderr += chunk;
+          if (backgrounded) {
+            try { appendFileSync(bgProcesses.get(child.pid!)?.logFile ?? "", chunk); } catch {}
+          }
+        });
+
+        // 超时处理：保持管道，标记为后台
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          backgrounded = true;
+
+          child.unref();
+
+          const logFile = `/tmp/oh-pi-bg-${Date.now()}.log`;
+          const pid = child.pid!;
+
+          // 把已有输出写入日志
+          writeFileSync(logFile, stdout + stderr);
+
+          const proc: BgProcess = { pid, command, logFile, startedAt: Date.now(), finished: false, exitCode: null };
+          bgProcesses.set(pid, proc);
+
+          // 监听完成事件，自动通知 LLM
+          child.on("close", (code) => {
+            proc.finished = true;
+            proc.exitCode = code;
+            const tail = (stdout + stderr).slice(-3000);
+            const truncated = (stdout + stderr).length > 3000 ? "[...truncated]\n" + tail : tail;
+            // 最终输出写入日志
+            try { writeFileSync(logFile, stdout + stderr); } catch {}
+
+            pi.sendMessage({
+              content: `[BG_PROCESS_DONE] PID ${pid} finished (exit ${code ?? "?"})\nCommand: ${command}\n\nOutput (last 3000 chars):\n${truncated}`,
+              display: true,
+              triggerTurn: true,
+              deliverAs: "followUp",
+            });
+          });
+
+          const preview = (stdout + stderr).slice(0, 500);
+          const text = `Command still running after ${effectiveTimeout / 1000}s, moved to background.\nPID: ${pid}\nLog: ${logFile}\nStop: kill ${pid}\n\nOutput so far:\n${preview}\n\n⏳ You will be notified automatically when it finishes. No need to poll.`;
+
+          resolve({
+            content: [{ type: "text", text }],
+            details: {},
+          });
+        }, effectiveTimeout);
+
+        // 正常结束（超时前）
+        child.on("close", (code) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+
+          const output = (stdout + stderr).trim();
+          const exitInfo = code !== 0 ? `\n[Exit code: ${code}]` : "";
+
+          resolve({
+            content: [{ type: "text", text: output + exitInfo }],
+            details: {},
+          });
+        });
+
+        child.on("error", (err) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+
+          resolve({
+            content: [{ type: "text", text: `Error: ${err.message}` }],
+            details: {},
+            isError: true,
+          });
+        });
+
+        // 处理 abort signal
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            try { child.kill(); } catch {}
+            resolve({
+              content: [{ type: "text", text: "Command cancelled." }],
+              details: {},
+            });
+          }, { once: true });
+        }
+      });
+    },
+  });
+
+  // bg_status 工具：查看/管理后台进程
+  pi.registerTool({
+    name: "bg_status",
+    label: "Background Process Status",
+    description: "Check status, view output, or stop background processes that were auto-backgrounded.",
+    parameters: Type.Object({
+      action: StringEnum(["list", "log", "stop"] as const, { description: "list=show all, log=view output, stop=kill process" }),
+      pid: Type.Optional(Type.Number({ description: "PID of the process (required for log/stop)" })),
+    }),
+    async execute(toolCallId, params) {
+      const { action, pid } = params;
+
+      if (action === "list") {
+        if (bgProcesses.size === 0) {
+          return { content: [{ type: "text", text: "No background processes." }], details: {} };
+        }
+        const lines = [...bgProcesses.values()].map((p) => {
+          const status = p.finished ? `⚪ stopped (exit ${p.exitCode ?? "?"})` : (isAlive(p.pid) ? "🟢 running" : "⚪ stopped");
+          return `PID: ${p.pid} | ${status} | Log: ${p.logFile}\n  Cmd: ${p.command}`;
+        });
+        return { content: [{ type: "text", text: lines.join("\n\n") }], details: {} };
+      }
+
+      if (!pid) {
+        return { content: [{ type: "text", text: "Error: pid is required for log/stop" }], details: {}, isError: true };
+      }
+
+      const proc = bgProcesses.get(pid);
+
+      if (action === "log") {
+        const logFile = proc?.logFile;
+        if (logFile && existsSync(logFile)) {
+          try {
+            const content = readFileSync(logFile, "utf-8");
+            const tail = content.slice(-5000);
+            const truncated = content.length > 5000 ? `[...truncated, showing last 5000 chars]\n${tail}` : tail;
+            return { content: [{ type: "text", text: truncated || "(empty)" }], details: {} };
+          } catch (e: any) {
+            return { content: [{ type: "text", text: `Error reading log: ${e.message}` }], details: {}, isError: true };
+          }
+        }
+        return { content: [{ type: "text", text: "No log available for this PID." }], details: {} };
+      }
+
+      if (action === "stop") {
+        try {
+          process.kill(pid, "SIGTERM");
+          bgProcesses.delete(pid);
+          return { content: [{ type: "text", text: `Process ${pid} terminated.` }], details: {} };
+        } catch {
+          bgProcesses.delete(pid);
+          return { content: [{ type: "text", text: `Process ${pid} not found (already stopped?).` }], details: {} };
+        }
+      }
+
+      return { content: [{ type: "text", text: `Unknown action: ${action}` }], details: {}, isError: true };
+    },
+  });
+
+  // 清理：退出时杀掉所有后台进程
+  pi.on("session_shutdown", async () => {
+    for (const [pid, proc] of bgProcesses) {
+      if (!proc.finished) {
+        try { process.kill(pid, "SIGTERM"); } catch {}
+      }
+    }
+    bgProcesses.clear();
+  });
+}
+
+function isAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}

package/config/pi/extensions/bg-process/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@xtrm/pi-bg-process",
+  "version": "1.0.0",
+  "description": "xtrm Pi extension: bg-process",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm"
+  ],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/compact-header/index.ts

@@ -0,0 +1,69 @@
+/**
+ * oh-pi Compact Header — table-style startup info with dynamic column widths
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { VERSION } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    ctx.ui.setHeader((_tui, theme) => ({
+      render(width: number): string[] {
+        const d = (s: string) => theme.fg("dim", s);
+        const a = (s: string) => theme.fg("accent", s);
+
+        const cmds = pi.getCommands();
+        const prompts = cmds.filter(c => c.source === "prompt").map(c => `/${c.name}`).join("  ");
+        const skills = cmds.filter(c => c.source === "skill").map(c => c.name).join("  ");
+        const model = ctx.model ? `${ctx.model.id}` : "no model";
+        const thinking = pi.getThinkingLevel();
+        const provider = ctx.model?.provider ?? "";
+
+        const pad = (s: string, w: number) => s + " ".repeat(Math.max(0, w - visibleWidth(s)));
+        const t = (s: string) => truncateToWidth(s, width);
+        const sep = d(" │ ");
+
+        // Right two columns are fixed width
+        const rCol = [
+          [d("esc"), a("interrupt"),   d("S-tab"), a("thinking")],
+          [d("^C"),  a("clear/exit"),  d("^O"),    a("expand")],
+          [d("^P"),  a("model"),       d("^G"),    a("editor")],
+          [d("/"),   a("commands"),    d("^V"),    a("paste")],
+          [d("!"),   a("bash"),        d(""),      a("")],
+        ];
+        const k1w = 6, v1w = 13, k2w = 6, v2w = 9;
+        const rightW = k1w + v1w + 3 + k2w + v2w + 3; // 3 for each sep
+
+        // Left column gets remaining space
+        const leftW = Math.max(20, width - rightW);
+        const lk = 9; // label width
+
+        const lCol = [
+          [d("version"), a(`v${VERSION}  ${provider}`)],
+          [d("model"),   a(model)],
+          [d("think"),   a(thinking)],
+          [d(""),        d("")],
+          [d(""),        d("")],
+        ];
+
+        const lines: string[] = [""];
+        for (let i = 0; i < 5; i++) {
+          const [lk0, lv0] = lCol[i];
+          const [rk0, rv0, rk1, rv1] = rCol[i];
+          const left = truncateToWidth(pad(lk0, lk) + lv0, leftW);
+          const right = pad(rk0, k1w) + pad(rv0, v1w) + sep + pad(rk1, k2w) + rv1;
+          lines.push(t(pad(left, leftW) + sep + right));
+        }
+
+        if (prompts) lines.push(t(`${pad(d("prompts"), lk)}${a(prompts)}`));
+        if (skills) lines.push(t(`${pad(d("skills"), lk)}${a(skills)}`));
+        lines.push(d("─".repeat(width)));
+
+        return lines;
+      },
+      invalidate() {},
+    }));
+  });
+}

package/config/pi/extensions/compact-header/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@xtrm/pi-compact-header",
+  "version": "1.0.0",
+  "description": "xtrm Pi extension: compact-header",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm"
+  ],
+  "author": "xtrm",
+  "license": "MIT"
+}

package/config/pi/extensions/core/adapter.ts

@@ -0,0 +1,52 @@
+import * as fs from "node:fs";
+import * as nodePath from "node:path";
+
+import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
+import { PI_MUTATING_FILE_TOOLS } from "./guard-rules";
+
+export class EventAdapter {
+	/**
+	 * Checks if the tool event is a mutating file operation (write, edit, etc).
+	 */
+	static isMutatingFileTool(event: ToolCallEvent<any, any>): boolean {
+		return PI_MUTATING_FILE_TOOLS.includes(event.toolName);
+	}
+
+	/**
+	 * Extracts the target path from a tool input, resolving against the current working directory.
+	 */
+	static extractPathFromToolInput(event: ToolCallEvent<any, any>, cwd: string): string | null {
+		const input = event.input;
+		if (!input) return null;
+
+		const pathRaw = input.path || input.file || input.filePath;
+		if (typeof pathRaw === "string") {
+			return pathRaw; // Usually Pi passes absolute paths anyway or paths relative to root
+		}
+
+		return null;
+	}
+
+	/**
+	 * Safely formats a block reason string to ensure UI readiness.
+	 */
+	static formatBlockReason(prefix: string, details: string): string {
+		return `${prefix}: ${details}`;
+	}
+	/**
+	 * Returns true if the given directory is a beads project (has a .beads directory).
+	 */
+	static isBeadsProject(cwd: string): boolean {
+		return fs.existsSync(nodePath.join(cwd, ".beads"));
+	}
+
+	/**
+	 * Parses the summary line from `bd list` output.
+	 * Returns { open, inProgress } or null if the line is absent.
+	 */
+	static parseBdCounts(output: string): { open: number; inProgress: number } | null {
+		const m = output.match(/Total:\s*\d+\s+issues?\s*\((\d+)\s+open,\s*(\d+)\s+in progress\)/);
+		if (!m) return null;
+		return { open: parseInt(m[1], 10), inProgress: parseInt(m[2], 10) };
+	}
+}

package/config/pi/extensions/core/guard-rules.ts

@@ -0,0 +1,102 @@
+// Canonical guard-rule constants for Pi extensions.
+// Mirrors hooks/guard-rules.mjs with Pi-specific tool naming where needed.
+
+export const PI_MUTATING_FILE_TOOLS = [
+	"write",
+	"edit",
+	"replace_content",
+	"replace_lines",
+	"delete_lines",
+	"insert_at_line",
+	"create_text_file",
+	"rename_symbol",
+	"replace_symbol_body",
+	"insert_after_symbol",
+	"insert_before_symbol",
+];
+
+export const SAFE_BASH_PREFIXES = [
+	// Git read-only
+	"git status",
+	"git log",
+	"git diff",
+	"git show",
+	"git blame",
+	"git branch",
+	"git fetch",
+	"git remote",
+	"git config",
+	"git pull",
+	"git stash",
+	"git worktree",
+	"git checkout -b",
+	"git switch -c",
+	// Tools
+	"gh",
+	"bd",
+	"npx gitnexus",
+	"xtrm finish",
+	// Read-only filesystem
+	"cat",
+	"ls",
+	"head",
+	"tail",
+	"pwd",
+	"which",
+	"type",
+	"env",
+	"printenv",
+	"find",
+	"grep",
+	"rg",
+	"fd",
+	"wc",
+	"sort",
+	"uniq",
+	"cut",
+	"awk",
+	"jq",
+	"yq",
+	"bat",
+	"less",
+	"more",
+	"file",
+	"stat",
+	"du",
+	"tree",
+	// Allowed writes (specific paths)
+	"touch .beads/",
+];
+
+export const DANGEROUS_BASH_PATTERNS = [
+	"sed\\s+-i",
+	"echo\\s+[^\\n]*>",
+	"printf\\s+[^\\n]*>",
+	"cat\\s+[^\\n]*>",
+	"tee\\b",
+	"(?:^|\\s)(?:vim|nano|vi)\\b",
+	"(?:^|\\s)mv\\b",
+	"(?:^|\\s)cp\\b",
+	"(?:^|\\s)rm\\b",
+	"(?:^|\\s)mkdir\\b",
+	"(?:^|\\s)touch\\b",
+	"(?:^|\\s)chmod\\b",
+	"(?:^|\\s)chown\\b",
+	">>",
+	"(?:^|\\s)git\\s+add\\b",
+	"(?:^|\\s)git\\s+commit\\b",
+	"(?:^|\\s)git\\s+merge\\b",
+	"(?:^|\\s)git\\s+push\\b",
+	"(?:^|\\s)git\\s+reset\\b",
+	"(?:^|\\s)git\\s+checkout\\b",
+	"(?:^|\\s)git\\s+rebase\\b",
+	"(?:^|\\s)git\\s+stash\\b",
+	"(?:^|\\s)npm\\s+install\\b",
+	"(?:^|\\s)bun\\s+install\\b",
+	"(?:^|\\s)bun\\s+add\\b",
+	"(?:^|\\s)node\\s+(?:-e|--eval)\\b",
+	"(?:^|\\s)bun\\s+(?:-e|--eval)\\b",
+	"(?:^|\\s)python\\s+-c\\b",
+	"(?:^|\\s)perl\\s+-e\\b",
+	"(?:^|\\s)ruby\\s+-e\\b",
+];

package/config/pi/extensions/core/lib.ts

@@ -0,0 +1,3 @@
+export * from "./logger";
+export * from "./runner";
+export * from "./adapter";

package/config/pi/extensions/core/logger.ts

@@ -0,0 +1,45 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LoggerOptions {
+	namespace: string;
+	level?: LogLevel;
+}
+
+export class Logger {
+	private namespace: string;
+	private level: LogLevel;
+
+	constructor(options: LoggerOptions) {
+		this.namespace = options.namespace;
+		this.level = options.level || "info";
+	}
+
+	private shouldLog(level: LogLevel): boolean {
+		const levels: LogLevel[] = ["debug", "info", "warn", "error"];
+		return levels.indexOf(level) >= levels.indexOf(this.level);
+	}
+
+	debug(message: string, ...args: any[]) {
+		if (this.shouldLog("debug")) {
+			console.debug(`[${this.namespace}] DEBUG: ${message}`, ...args);
+		}
+	}
+
+	info(message: string, ...args: any[]) {
+		if (this.shouldLog("info")) {
+			console.info(`[${this.namespace}] INFO: ${message}`, ...args);
+		}
+	}
+
+	warn(message: string, ...args: any[]) {
+		if (this.shouldLog("warn")) {
+			console.warn(`[${this.namespace}] WARN: ${message}`, ...args);
+		}
+	}
+
+	error(message: string, ...args: any[]) {
+		if (this.shouldLog("error")) {
+			console.error(`[${this.namespace}] ERROR: ${message}`, ...args);
+		}
+	}
+}

package/config/pi/extensions/core/runner.ts

@@ -0,0 +1,71 @@
+import { execFile, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface RunOptions {
+	timeoutMs?: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	input?: string; // Standard input
+}
+
+export interface RunResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export class SubprocessRunner {
+	/**
+	 * Run a command deterministically with a timeout and optional stdin.
+	 */
+	static async run(
+		command: string,
+		args: string[],
+		options: RunOptions = {}
+	): Promise<RunResult> {
+		const timeout = options.timeoutMs ?? 10000;
+		const cwd = options.cwd ?? process.cwd();
+		const env = { ...process.env, ...options.env };
+
+		if (options.input !== undefined) {
+			// Use spawnSync for stdin support if input is provided
+			const result = spawnSync(command, args, {
+				cwd,
+				env,
+				input: options.input,
+				encoding: "utf8",
+				timeout,
+				maxBuffer: 1024 * 1024 * 10,
+			});
+
+			return {
+				code: result.status ?? 1,
+				stdout: (result.stdout ?? "").trim(),
+				stderr: (result.stderr ?? "").trim(),
+			};
+		}
+
+		try {
+			const result = await execFileAsync(command, args, {
+				timeout,
+				cwd,
+				env,
+				maxBuffer: 1024 * 1024 * 10,
+			});
+
+			return {
+				code: 0,
+				stdout: result.stdout.trim(),
+				stderr: result.stderr.trim(),
+			};
+		} catch (error: any) {
+			return {
+				code: error.code ?? 1,
+				stdout: (error.stdout ?? "").trim(),
+				stderr: (error.stderr ?? error.message ?? "").trim(),
+			};
+		}
+	}
+}

package/config/pi/extensions/core/session-state.ts

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+export type SessionPhase =
+  | 'claimed'
+  | 'phase1-done'
+  | 'waiting-merge'
+  | 'conflicting'
+  | 'pending-cleanup'
+  | 'merged'
+  | 'cleanup-done';
+
+export interface SessionState {
+  issueId: string;
+  branch: string;
+  worktreePath: string;
+  prNumber: number | null;
+  prUrl: string | null;
+  phase: SessionPhase;
+  conflictFiles: string[];
+  startedAt: string;
+  lastChecked: string;
+}
+
+const SESSION_STATE_FILE = '.xtrm-session-state.json';
+
+export function findSessionStateFile(startCwd: string): string | null {
+  let current = path.resolve(startCwd || process.cwd());
+  for (;;) {
+    const candidate = path.join(current, SESSION_STATE_FILE);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function readSessionState(startCwd: string): SessionState | null {
+  const filePath = findSessionStateFile(startCwd);
+  if (!filePath) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (!parsed.issueId || !parsed.branch || !parsed.worktreePath || !parsed.phase) return null;
+    return {
+      issueId: String(parsed.issueId),
+      branch: String(parsed.branch),
+      worktreePath: String(parsed.worktreePath),
+      prNumber: parsed.prNumber ?? null,
+      prUrl: parsed.prUrl ?? null,
+      phase: parsed.phase,
+      conflictFiles: Array.isArray(parsed.conflictFiles) ? parsed.conflictFiles.map(String) : [],
+      startedAt: String(parsed.startedAt || ''),
+      lastChecked: String(parsed.lastChecked || ''),
+    } as SessionState;
+  } catch {
+    return null;
+  }
+}