@sreetej510/pi-hpc-tools 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @sreetej510/pi-hpc-tools
+
+A [pi](https://github.com/earendil-works/pi) coding agent extension for exploring a remote
+HPC/SSH host through [`plink`](https://www.chiark.greenend.org.uk/~sgtatham/putty/) without
+ever leaving your local project.
+
+## What it does
+
+- Adds three read-only tools — `ls_hpc`, `read_file_hpc`, `grep_hpc` — that shell out to a
+  remote host via `plink -batch -pw "<password>" <user>@<host> "<command>"`.
+- Tools are only active in projects where you've explicitly run `/hpc:on`, so the model never
+  gets silent access to a remote machine.
+- On/off state is stored per-project in `hpc-config.json` (`enabledProjects: ["/path/to/project", ...]`),
+  and restored automatically on resume/session switch.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/hpc:on` | Enable the HPC tools for the current project |
+| `/hpc:off` | Disable the HPC tools for the current project |
+| `/hpc:config` | Configure host/user/password/plink path |
+
+## Configuration
+
+Credentials are resolved in this order:
+
+1. Environment variables: `HPC_USERNAME` (or `HPC_USER`), `HPC_HOST`, `HPC_PASSWORD`.
+2. `hpc-config.json` (in `~/.pi/agent/.pi/` or `~/.pi/`), written by `/hpc:config`:
+
+   ```json
+   {
+     "username": "...",
+     "host": "...",
+     "password": "...",
+     "plinkPath": "C:/path/to/plink.exe",
+     "enabledProjects": ["/path/to/project"]
+   }
+   ```
+
+3. `PLINK_PATH` env var, or `plinkPath` in the config file, or the default Windows/Git-Bash
+   `plink.exe` path — falls back to `plink` on `PATH` otherwise.
+
+The shell used to invoke `plink` is read from your pi `settings.json` (`shellPath`), defaulting
+to Git Bash on Windows and `bash` elsewhere.
+
+## Install
+
+```bash
+npm install -g @sreetej510/pi-hpc-tools
+```
+
+Then add it to your pi `settings.json`:
+
+```json
+{
+  "packages": ["npm:@sreetej510/pi-hpc-tools"]
+}
+```
+
+Or, for local development, point at the file directly:
+
+```json
+{
+  "extensions": ["/absolute/path/to/pi-extensions/extensions/pi-hpc-tools/src/index.ts"]
+}
+```
+
+## File layout
+
+| File | Responsibility |
+|---|---|
+| `src/index.ts` | Extension entry point: commands (`/hpc:on`, `/hpc:off`, `/hpc:config`) + lifecycle events |
+| `src/constants.ts` | Tool names, timeouts, config file paths |
+| `src/types.ts` | Shared TypeScript types |
+| `src/state.ts` | Shared mutable module state (enabled flag, config cache, sync flags) |
+| `src/config.ts` | `hpc-config.json` load/save, per-project enable state, shell/plink resolution |
+| `src/exec.ts` | `plink` invocation + shell quoting helpers |
+| `src/grep-options.ts` | `grep_hpc` option-string building heuristics |
+| `src/render.ts` | Tool call/result rendering |
+| `src/tool-sync.ts` | Keeps the HPC tools' active/inactive state in sync with `/hpc:on`/`/hpc:off` |
+| `src/tools.ts` | Registers `ls_hpc` / `read_file_hpc` / `grep_hpc` |
+
+## Development
+
+```bash
+npm install
+npm run --workspace @sreetej510/pi-hpc-tools check     # biome + typecheck
+npm run --workspace @sreetej510/pi-hpc-tools format
+```
+
+## Security notes
+
+- Credentials are stored in plaintext JSON on disk (matching plink's own `-pw` usage) — treat
+  `hpc-config.json` like any other secret file and keep it out of version control.
+- Tools are strictly read-only (`ls`, `read`, `grep`); there is no remote write/execute tool.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sreetej510/pi-hpc-tools",
+  "version": "0.1.1",
+  "description": "Pi extension for exploring a remote HPC/SSH host (via plink) with ls/read/grep tools, gated per-project by /hpc:on and /hpc:off.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "hpc",
+    "ssh",
+    "plink",
+    "remote"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "typebox": "^1.3.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-tui": "^0.80.3",
+    "typescript": "^5.7.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sreetej510/pi-extensions",
+    "directory": "extensions/pi-hpc-tools"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,97 @@
+/** hpc-config.json load/save + per-project enable state + shell/plink resolution. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENT_DIR, CONFIG_PATHS, DEFAULT_PLINK } from "./constants.js";
+import { getCurrentConfig, setCurrentConfig } from "./state.js";
+import type { HPCConfig } from "./types.js";
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function isProjectEnabled(config: HPCConfig, cwd: string): boolean {
+  return (config.enabledProjects ?? []).includes(cwd);
+}
+
+export function setProjectEnabled(cwd: string, enabled: boolean): void {
+  const config = getHPCConfig();
+  if (!config) return;
+  const projects = new Set(config.enabledProjects ?? []);
+  if (enabled) {
+    projects.add(cwd);
+  } else {
+    projects.delete(cwd);
+  }
+  saveConfig({ ...config, enabledProjects: [...projects] });
+}
+
+export function loadConfig(): HPCConfig | null {
+  const username = process.env.HPC_USERNAME || process.env.HPC_USER;
+  const host = process.env.HPC_HOST;
+  const password = process.env.HPC_PASSWORD;
+  if (username && host && password) {
+    return { username, host, password };
+  }
+
+  for (const configPath of CONFIG_PATHS) {
+    try {
+      if (!existsSync(configPath)) continue;
+      const config = JSON.parse(readFileSync(configPath, "utf-8")) as HPCConfig;
+      if (config.username && config.host && config.password) {
+        return config;
+      }
+    } catch {
+      // try next path
+    }
+  }
+  return null;
+}
+
+export function saveConfig(config: HPCConfig): void {
+  const configPath = CONFIG_PATHS[0];
+  ensureDir(configPath);
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+  setCurrentConfig(config);
+}
+
+export function getHPCConfig(): HPCConfig | null {
+  if (!getCurrentConfig()) {
+    setCurrentConfig(loadConfig());
+  }
+  return getCurrentConfig();
+}
+
+/** Forward-slash path for Git Bash (C:/Users/...). */
+export function toSlashPath(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function getAgentSettings(): { shellPath?: string } {
+  try {
+    const settingsPath = join(AGENT_DIR, "settings.json");
+    if (existsSync(settingsPath)) {
+      return JSON.parse(readFileSync(settingsPath, "utf-8")) as { shellPath?: string };
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+/** Shell from settings.json shellPath — must match user bash (Git Bash on Windows). */
+export function getShellExecutable(): string {
+  const fromSettings = getAgentSettings().shellPath;
+  if (fromSettings) return fromSettings;
+  return process.platform === "win32" ? "C:\\Program Files\\Git\\bin\\bash.exe" : "bash";
+}
+
+export function getPlinkCommand(): string {
+  if (process.env.PLINK_PATH) return toSlashPath(process.env.PLINK_PATH);
+  const cfg = getHPCConfig();
+  if (cfg?.plinkPath) return toSlashPath(cfg.plinkPath);
+  if (existsSync(DEFAULT_PLINK)) return DEFAULT_PLINK;
+  return "plink";
+}

package/src/constants.ts

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HPC_TOOL_NAMES = ["ls_hpc", "read_file_hpc", "grep_hpc"] as const;
+export const MAX_READ_LINES = 1000;
+export const GREP_TIMEOUT_MS = 120_000;
+export const UI_PREVIEW_LINES = 10;
+
+export const AGENT_DIR = join(homedir(), ".pi", "agent");
+export const CONFIG_PATHS = [join(AGENT_DIR, ".pi", "hpc-config.json"), join(homedir(), ".pi", "hpc-config.json")];
+
+/** Default plink on this machine (Git bash path). Override via PLINK_PATH or hpc-config.json plinkPath. */
+export const DEFAULT_PLINK = "C:/Users/sreet/plink/plink.exe";

package/src/exec.ts

@@ -0,0 +1,49 @@
+/** Remote command execution over plink + shell quoting helpers. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getHPCConfig, getPlinkCommand, getShellExecutable } from "./config.js";
+import type { HpcExecResult } from "./types.js";
+
+/** Single-quote escape for remote shell command strings. */
+export function shQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+export function bashQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export async function execOnHPC(
+  pi: ExtensionAPI,
+  remoteCommand: string,
+  opts?: { timeout?: number; signal?: AbortSignal },
+): Promise<HpcExecResult> {
+  const config = getHPCConfig();
+  if (!config) {
+    throw new Error("HPC not configured. Use /hpc:config username@host password");
+  }
+
+  const plink = bashQuote(getPlinkCommand());
+  const localCmd = `${plink} -batch -pw ${bashQuote(config.password)} ${config.username}@${config.host} ${bashQuote(remoteCommand)}`;
+  const connectTimeoutMs = opts?.timeout ?? 60_000;
+  const result = await pi.exec(getShellExecutable(), ["-c", localCmd], {
+    signal: opts?.signal,
+    timeout: connectTimeoutMs,
+  });
+
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    exitCode: result.code ?? 0,
+    killed: result.killed,
+  };
+}
+
+export function isHpcFailure(result: HpcExecResult): boolean {
+  const text = `${result.stdout}\n${result.stderr}`;
+  return result.exitCode !== 0 || /FATAL ERROR/i.test(text);
+}
+
+export function formatHpcFailure(result: HpcExecResult): string {
+  if (result.killed) return "HPC command timed out.";
+  return (result.stderr || result.stdout).trim() || `HPC command failed (exit ${result.exitCode})`;
+}

package/src/grep-options.ts

@@ -0,0 +1,57 @@
+/** grep_hpc option-string building heuristics. */
+
+function grepUsesFixedStrings(options: string): boolean {
+  return /(?:^|\s)-F(?:\s|$)/.test(options) || /--fixed-strings/.test(options);
+}
+
+function grepUsesExtendedRegex(options: string): boolean {
+  return /(?:^|\s)-E(?:\s|$)/.test(options) || /--extended-regexp/.test(options);
+}
+
+/** Heuristic: | alternation and common ERE syntax need grep -E. */
+function patternNeedsExtendedRegex(pattern: string): boolean {
+  if (pattern.includes("|")) return true;
+  if (/[()[\]+]/.test(pattern)) return true;
+  if (/(?:^|[^\\])\?/.test(pattern)) return true;
+  return false;
+}
+
+function isLikelyFilePath(path: string): boolean {
+  const base = path.split("/").pop() ?? path;
+  return base.includes(".") && !path.endsWith("/");
+}
+
+export function buildGrepOptions(
+  baseOptions: string,
+  pattern: string,
+  searchPath: string,
+  params: {
+    recursive?: boolean;
+    context?: number;
+    after?: number;
+    before?: number;
+  },
+): string {
+  let opts = baseOptions.trim();
+  opts = opts.replace(/-(?:A|B|C)\s*\d+/g, "").trim();
+
+  if (!grepUsesFixedStrings(opts) && !grepUsesExtendedRegex(opts) && patternNeedsExtendedRegex(pattern)) {
+    opts += " -E";
+  }
+
+  if (params.context !== undefined && params.context > 0) {
+    opts += ` -C ${params.context}`;
+  } else {
+    if (params.after && params.after > 0) opts += ` -A ${params.after}`;
+    if (params.before && params.before > 0) opts += ` -B ${params.before}`;
+  }
+
+  const useRecursive = params.recursive !== false && !isLikelyFilePath(searchPath);
+  if (!useRecursive) {
+    opts = opts.replace(/\s*-r\b/g, "").trim();
+  } else if (!/\s-r\b/.test(opts)) {
+    opts += " -r";
+  }
+
+  return opts.replace(/\s+/g, " ").trim();
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+/**
+ * HPC Tools Extension for pi
+ *
+ * Remote file exploration via plink:
+ *   plink -batch -pw "password" username@host "command"
+ *
+ * Commands: /hpc:on, /hpc:off, /hpc:config
+ * Tools (active only after /hpc:on in this project): ls_hpc, read_file_hpc, grep_hpc
+ * On/off state is stored in hpc-config.json as enabledProjects: ["/path/to/project", ...]
+ *
+ * File layout:
+ *   index.ts        extension entry point (this file) — commands + lifecycle events
+ *   constants.ts    tool names, timeouts, config file paths
+ *   types.ts        shared TypeScript types
+ *   state.ts        shared mutable module state (enabled flag, config cache, sync flags)
+ *   config.ts       hpc-config.json load/save, per-project enable state, shell/plink resolution
+ *   exec.ts         plink invocation + shell quoting helpers
+ *   grep-options.ts grep_hpc option-string building heuristics
+ *   render.ts       tool call/result rendering
+ *   tool-sync.ts    keeps HPC tools' active/inactive state in sync with /hpc:on|off
+ *   tools.ts        registers ls_hpc / read_file_hpc / grep_hpc
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getHPCConfig, loadConfig, saveConfig } from "./config.js";
+import { getHpcEnabled, getPendingToolSync, setCurrentConfig } from "./state.js";
+import { isHpcSyncNeeded, onProjectContext, scheduleDelayedHpcSync, setHpcEnabled, syncHpcTools } from "./tool-sync.js";
+
+export default function hpcToolsExtension(pi: ExtensionAPI) {
+  setCurrentConfig(loadConfig());
+
+  pi.registerCommand("hpc:on", {
+    description: "Enable HPC tools for this project folder",
+    handler: async (_args, ctx) => {
+      const config = getHPCConfig();
+      if (!config) {
+        ctx.ui.notify("HPC not configured. Use /hpc:config username@host password", "error");
+        return;
+      }
+      setHpcEnabled(pi, ctx.cwd, true);
+      ctx.ui.notify(`HPC tools ON in this project (${config.username}@${config.host})`, "info");
+      ctx.ui.setStatus("hpc", `HPC: ON`);
+    },
+  });
+
+  pi.registerCommand("hpc:off", {
+    description: "Disable HPC tools for this project folder (other tools unchanged)",
+    handler: async (_args, ctx) => {
+      setHpcEnabled(pi, ctx.cwd, false);
+      ctx.ui.notify("HPC tools OFF in this project", "info");
+      ctx.ui.setStatus("hpc", `HPC: OFF`);
+    },
+  });
+
+  pi.registerCommand("hpc:config", {
+    description: "Set HPC credentials: /hpc:config username@host password",
+    handler: async (args, ctx) => {
+      if (!args?.trim()) {
+        ctx.ui.notify("Usage: /hpc:config username@host password", "info");
+        ctx.ui.notify("   or: /hpc:config username host password", "info");
+        return;
+      }
+
+      const parts = args.trim().split(/\s+/);
+      let username: string;
+      let host: string;
+      let password: string;
+
+      if (parts.length === 2) {
+        const at = parts[0].indexOf("@");
+        if (at === -1) {
+          ctx.ui.notify("Use username@host password", "error");
+          return;
+        }
+        username = parts[0].slice(0, at);
+        host = parts[0].slice(at + 1);
+        password = parts[1];
+      } else if (parts.length >= 3) {
+        username = parts[0];
+        host = parts[1];
+        password = parts.slice(2).join(" ");
+      } else {
+        ctx.ui.notify("Usage: /hpc:config username@host password", "error");
+        return;
+      }
+
+      saveConfig({ username, host, password });
+      ctx.ui.notify(`HPC configured: ${username}@${host}`, "info");
+      ctx.ui.setStatus("hpc", `HPC: ${getHpcEnabled() ? "ON" : "OFF"}`);
+    },
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    // New, resume, reload, fork — re-apply per-project hpc-state.json
+    onProjectContext(pi, ctx.cwd);
+    if (event.reason === "resume" || event.reason === "reload" || event.reason === "startup") {
+      scheduleDelayedHpcSync(pi);
+    }
+
+    const config = getHPCConfig();
+    if (config) {
+      ctx.ui.setStatus("hpc", `HPC: ${getHpcEnabled() ? "ON" : "OFF"}`);
+    } else if (getHpcEnabled()) {
+      ctx.ui.setStatus("hpc", `HPC: ON (not configured)`);
+    }
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    // Navigating branches in an existing session — active tools may be restored from history
+    onProjectContext(pi, ctx.cwd);
+  });
+
+  pi.on("before_agent_start", async () => {
+    if (!getPendingToolSync() && !isHpcSyncNeeded(pi)) return;
+    syncHpcTools(pi);
+  });
+}

package/src/render.ts

@@ -0,0 +1,68 @@
+/** Tool call/result rendering — matches built-in ls/grep/read formatting. */
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { UI_PREVIEW_LINES } from "./constants.js";
+import type { HpcToolRenderResult } from "./types.js";
+
+function getToolText(result: HpcToolRenderResult): string {
+  const block = result.content.find((c) => c.type === "text");
+  return block?.type === "text" ? (block.text ?? "") : "";
+}
+
+/** Match built-in ls/grep/read renderResult formatting (in-place expand via Ctrl+O). */
+export function formatHpcResult(
+  result: HpcToolRenderResult,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: import("@earendil-works/pi-coding-agent").Theme,
+): string {
+  if (options.isPartial) {
+    return theme.fg("warning", "Connecting to HPC...");
+  }
+
+  const details = result.details ?? {};
+  const output = getToolText(result).trim();
+  const exitCode = details.exitCode as number | undefined;
+
+  if (details.error || (exitCode !== undefined && exitCode !== 0)) {
+    return theme.fg("error", output || `HPC command failed (exit ${exitCode ?? "?"})`);
+  }
+
+  if (!output) {
+    return theme.fg("dim", "(no output)");
+  }
+
+  const lines = output.split("\n");
+  const maxLines = options.expanded ? lines.length : UI_PREVIEW_LINES;
+  const displayLines = lines.slice(0, maxLines);
+  const remaining = lines.length - maxLines;
+
+  let text = `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+  if (remaining > 0) {
+    text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")})`;
+  }
+  if (details.truncatedForAgent) {
+    text += `\n${theme.fg("warning", "[Truncated for agent — narrow path or pattern]")}`;
+  }
+  return text;
+}
+
+export function hpcRenderCall(
+  callText: string,
+  theme: import("@earendil-works/pi-coding-agent").Theme,
+  context: { lastComponent?: unknown },
+): Text {
+  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+  text.setText(callText);
+  return text;
+}
+
+export function hpcRenderResult(
+  result: HpcToolRenderResult,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: import("@earendil-works/pi-coding-agent").Theme,
+  context: { lastComponent?: unknown },
+): Text {
+  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+  text.setText(formatHpcResult(result, options, theme));
+  return text;
+}

package/src/state.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared mutable module state, centralized here so every other file mutates
+ * it through explicit getters/setters instead of each holding its own copy.
+ */
+import type { HPCConfig } from "./types.js";
+
+let hpcEnabled = false;
+let currentConfig: HPCConfig | null = null;
+let toolsRegistered = false;
+/** Sync HPC tool visibility after built-ins are in the active set. */
+let pendingToolSync = false;
+
+export function getHpcEnabled(): boolean {
+  return hpcEnabled;
+}
+
+export function setHpcEnabledFlag(enabled: boolean): void {
+  hpcEnabled = enabled;
+}
+
+export function getCurrentConfig(): HPCConfig | null {
+  return currentConfig;
+}
+
+export function setCurrentConfig(config: HPCConfig | null): void {
+  currentConfig = config;
+}
+
+export function getToolsRegistered(): boolean {
+  return toolsRegistered;
+}
+
+export function setToolsRegistered(registered: boolean): void {
+  toolsRegistered = registered;
+}
+
+export function getPendingToolSync(): boolean {
+  return pendingToolSync;
+}
+
+export function setPendingToolSync(pending: boolean): void {
+  pendingToolSync = pending;
+}

package/src/tool-sync.ts

@@ -0,0 +1,114 @@
+/** Keeps the ls_hpc/read_file_hpc/grep_hpc tools' active/inactive state in sync with /hpc:on|off. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getHPCConfig, isProjectEnabled, loadConfig, setProjectEnabled } from "./config.js";
+import { HPC_TOOL_NAMES } from "./constants.js";
+import {
+  getHpcEnabled,
+  getPendingToolSync,
+  getToolsRegistered,
+  setCurrentConfig,
+  setHpcEnabledFlag,
+  setPendingToolSync,
+} from "./state.js";
+import { registerHPCTools } from "./tools.js";
+
+const HPC_TOOL_SET = new Set<string>(HPC_TOOL_NAMES);
+
+function isHpcToolName(name: string): boolean {
+  return HPC_TOOL_SET.has(name);
+}
+
+/** pi.getActiveTools() returns tool name strings (not { name } objects). */
+function getActiveToolNames(pi: ExtensionAPI): string[] {
+  const active = pi.getActiveTools() as Array<string | { name: string }>;
+  return active.map((t) => (typeof t === "string" ? t : t.name));
+}
+
+function wantHpcEnabled(): boolean {
+  return getHpcEnabled() && Boolean(getHPCConfig());
+}
+
+function hasHpcInActive(pi: ExtensionAPI): boolean {
+  return HPC_TOOL_NAMES.some((n) => getActiveToolNames(pi).includes(n));
+}
+
+export function isHpcSyncNeeded(pi: ExtensionAPI): boolean {
+  return wantHpcEnabled() !== hasHpcInActive(pi);
+}
+
+function ensureHpcToolsRegistered(pi: ExtensionAPI): void {
+  if (getToolsRegistered()) return;
+  registerHPCTools(pi);
+}
+
+/**
+ * Toggle only the three HPC tools on the current active set.
+ * ON: add HPC tools to whatever is already active (keeps all other tools).
+ * OFF: remove HPC tools from whatever is active (keeps all other tools).
+ */
+function applyHpcToolVisibility(pi: ExtensionAPI, enabled: boolean): void {
+  const current = getActiveToolNames(pi);
+
+  if (enabled) {
+    if (current.length === 0) {
+      setPendingToolSync(true);
+      return;
+    }
+    const next = new Set(current);
+    for (const name of HPC_TOOL_NAMES) next.add(name);
+    pi.setActiveTools([...next]);
+  } else {
+    const withoutHpc = current.filter((n) => !isHpcToolName(n));
+    if (withoutHpc.length !== current.length) {
+      pi.setActiveTools(withoutHpc);
+    }
+  }
+
+  setPendingToolSync(isHpcSyncNeeded(pi));
+}
+
+/** Apply project hpc-state.json to the active tool list (resume / session switch). */
+export function syncHpcTools(pi: ExtensionAPI): void {
+  const want = wantHpcEnabled();
+  if (want) {
+    ensureHpcToolsRegistered(pi);
+  }
+  applyHpcToolVisibility(pi, want);
+}
+
+export function scheduleHpcSync(pi: ExtensionAPI, attempt = 0): void {
+  const want = wantHpcEnabled();
+  const active = getActiveToolNames(pi);
+
+  if (want && active.length === 0 && attempt < 8) {
+    queueMicrotask(() => scheduleHpcSync(pi, attempt + 1));
+    return;
+  }
+
+  syncHpcTools(pi);
+}
+
+/** Resume/reload restores active tools from the session file after session_start. */
+export function scheduleDelayedHpcSync(pi: ExtensionAPI): void {
+  for (const delayMs of [0, 50, 150, 400]) {
+    setTimeout(() => {
+      if (getPendingToolSync() || isHpcSyncNeeded(pi)) {
+        syncHpcTools(pi);
+      }
+    }, delayMs);
+  }
+}
+
+export function setHpcEnabled(pi: ExtensionAPI, cwd: string, enabled: boolean): void {
+  setHpcEnabledFlag(enabled);
+  setProjectEnabled(cwd, enabled);
+  syncHpcTools(pi);
+}
+
+export function onProjectContext(pi: ExtensionAPI, cwd: string): void {
+  const config = loadConfig();
+  setCurrentConfig(config);
+  setHpcEnabledFlag(config ? isProjectEnabled(config, cwd) : false);
+  setPendingToolSync(true);
+  scheduleHpcSync(pi);
+}

package/src/tools.ts

@@ -0,0 +1,295 @@
+/** Registers the ls_hpc / read_file_hpc / grep_hpc tools. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GREP_TIMEOUT_MS, MAX_READ_LINES } from "./constants.js";
+import { execOnHPC, formatHpcFailure, isHpcFailure, shQuote } from "./exec.js";
+import { buildGrepOptions } from "./grep-options.js";
+import { hpcRenderCall, hpcRenderResult } from "./render.js";
+import { getToolsRegistered, setToolsRegistered } from "./state.js";
+
+export function registerHPCTools(pi: ExtensionAPI): void {
+  if (getToolsRegistered()) return;
+  setToolsRegistered(true);
+
+  const sharedRender = hpcRenderResult;
+
+  pi.registerTool({
+    name: "ls_hpc",
+    label: "List HPC Directory",
+    description:
+      "List files and directories on the remote HPC system. Use recursive=true to list all files under a directory.",
+    promptSnippet: "List or browse files on remote HPC",
+    promptGuidelines: [
+      "Use ls_hpc when the user wants to explore directories on the remote HPC filesystem.",
+      "Use ls_hpc with recursive=true to enumerate files under a directory tree.",
+    ],
+    parameters: Type.Object({
+      path: Type.Optional(Type.String({ description: "Directory on HPC. Defaults to home (~)." })),
+      options: Type.Optional(
+        Type.String({ description: "Extra ls flags (e.g. -lh). Default: -la. Ignored when recursive=true." }),
+      ),
+      recursive: Type.Optional(Type.Boolean({ description: "List all files recursively under path. Default: false." })),
+    }),
+    renderCall(args, theme, context) {
+      const path = (args.path as string) || "~";
+      const rec = args.recursive ? " (recursive)" : "";
+      const callText = theme.fg("toolTitle", theme.bold("ls_hpc ")) + theme.fg("accent", path) + theme.fg("muted", rec);
+      return hpcRenderCall(callText, theme, context);
+    },
+    renderResult: sharedRender,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({ content: [{ type: "text", text: "Listing on HPC..." }], details: undefined });
+      const path = params.path || "~";
+      const recursive = params.recursive ?? false;
+      const options = params.options || "-la";
+
+      const command = recursive
+        ? `find ${shQuote(path)} -type f 2>/dev/null | head -n 50000 | sort`
+        : `ls ${options} ${shQuote(path)} 2>&1`;
+
+      const result = await execOnHPC(pi, command, { signal });
+
+      if (isHpcFailure(result)) {
+        return {
+          content: [{ type: "text", text: formatHpcFailure(result) }],
+          details: { exitCode: result.exitCode, path, recursive, error: true },
+          isError: true,
+        };
+      }
+
+      const text = (result.stdout || "").trim() || "(empty)";
+      return {
+        content: [{ type: "text", text }],
+        details: { exitCode: result.exitCode, path, recursive, lineCount: text.split("\n").length },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "read_file_hpc",
+    label: "Read HPC File",
+    description: `Read a file from remote HPC. Supports offset/limit line range (max ${MAX_READ_LINES} lines per call).`,
+    promptSnippet: "Read file contents from remote HPC",
+    promptGuidelines: [
+      "Use read_file_hpc to view source or config files stored on HPC.",
+      `Use offset and limit to paginate large files (max ${MAX_READ_LINES} lines per read).`,
+    ],
+    parameters: Type.Object({
+      path: Type.String({ description: "Absolute or relative file path on HPC." }),
+      offset: Type.Optional(Type.Integer({ description: "0-based starting line. Default: 0.", minimum: 0 })),
+      limit: Type.Optional(
+        Type.Integer({
+          description: `Max lines to read (capped at ${MAX_READ_LINES}). Default: ${MAX_READ_LINES}.`,
+          minimum: 1,
+          maximum: MAX_READ_LINES,
+        }),
+      ),
+    }),
+    renderCall(args, theme, context) {
+      const path = args.path as string;
+      const offset = (args.offset as number | undefined) ?? 0;
+      const limit = (args.limit as number | undefined) ?? MAX_READ_LINES;
+      const callText =
+        theme.fg("toolTitle", theme.bold("read_file_hpc ")) +
+        theme.fg("accent", path) +
+        theme.fg("warning", `:${offset + 1}${limit ? `-${offset + limit}` : ""}`);
+      return hpcRenderCall(callText, theme, context);
+    },
+    renderResult: sharedRender,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({ content: [{ type: "text", text: "Reading from HPC..." }], details: undefined });
+      const filePath = params.path;
+      const offset = Math.max(0, params.offset ?? 0);
+      let limit = params.limit ?? MAX_READ_LINES;
+      if (limit > MAX_READ_LINES) limit = MAX_READ_LINES;
+
+      const startLine = offset + 1;
+      const endLine = offset + limit;
+      const command = `sed -n '${startLine},${endLine}p' ${shQuote(filePath)} 2>&1`;
+
+      const result = await execOnHPC(pi, command, { signal });
+      const output = result.stdout ?? "";
+      const err = result.stderr ?? "";
+
+      if (result.exitCode !== 0) {
+        return {
+          content: [{ type: "text", text: `Error reading ${filePath}:\n${err || output || "(no output)"}` }],
+          details: { exitCode: result.exitCode, path: filePath, error: true },
+        };
+      }
+
+      if (!output.trim()) {
+        return {
+          content: [{ type: "text", text: `No content in lines ${startLine}-${endLine} of ${filePath}` }],
+          details: { path: filePath, offset, limit, empty: true },
+        };
+      }
+
+      const lineCount = output.split("\n").length;
+      const header = `${filePath} (lines ${startLine}-${offset + lineCount}):\n`;
+      return {
+        content: [{ type: "text", text: header + output }],
+        details: { path: filePath, offset, limit, lines: lineCount },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "grep_hpc",
+    label: "Search HPC Files",
+    description:
+      "Search file contents on HPC with grep. Patterns with | (alternation) auto-use grep -E. Use options '-F' for literal/fixed-string search. Max runtime 2 minutes.",
+    promptSnippet: "Grep/search text in remote HPC files",
+    promptGuidelines: [
+      "Use grep_hpc to find strings or regex patterns in HPC files.",
+      "For alternation (foo|bar), use one pattern with | — grep -E is added automatically.",
+      "Use options '-F' when the pattern must be matched literally (no regex).",
+      "Use after/before/context for surrounding lines (like grep -A/-B/-C).",
+    ],
+    parameters: Type.Object({
+      pattern: Type.String({ description: "Search pattern. Use | for alternation (e.g. foo|bar)." }),
+      path: Type.Optional(Type.String({ description: "File or directory on HPC. Default: ." })),
+      options: Type.Optional(
+        Type.String({
+          description: "Extra grep flags (e.g. -i, -l, -E). Default base: -rn.",
+        }),
+      ),
+      file_pattern: Type.Optional(
+        Type.String({
+          description:
+            "Glob for filenames to search, e.g. '*.csv' or '*.py' (uses grep --include, case-insensitive via find when non-recursive).",
+        }),
+      ),
+      after: Type.Optional(Type.Integer({ description: "Lines after match (grep -A).", minimum: 0 })),
+      before: Type.Optional(Type.Integer({ description: "Lines before match (grep -B).", minimum: 0 })),
+      context: Type.Optional(
+        Type.Integer({ description: "Lines before and after (grep -C). Overrides after/before.", minimum: 0 }),
+      ),
+      recursive: Type.Optional(Type.Boolean({ description: "Search recursively (-r). Default true for directories." })),
+    }),
+    renderCall(args, theme, context) {
+      let callText = theme.fg("toolTitle", theme.bold("grep_hpc "));
+      callText += theme.fg("accent", `"${args.pattern as string}"`);
+      if (args.path) callText += theme.fg("toolOutput", ` in ${args.path as string}`);
+      if (args.file_pattern) callText += theme.fg("toolOutput", ` (${args.file_pattern as string})`);
+      return hpcRenderCall(callText, theme, context);
+    },
+    renderResult: sharedRender,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({ content: [{ type: "text", text: "Searching on HPC..." }], details: undefined });
+
+      const pattern = params.pattern;
+      const searchPath = params.path || ".";
+      const grepOpts = buildGrepOptions(params.options || "-n", pattern, searchPath, {
+        recursive: params.recursive,
+        context: params.context,
+        after: params.after,
+        before: params.before,
+      });
+      const quotedPattern = shQuote(pattern);
+      const quotedPath = shQuote(searchPath);
+
+      let command: string;
+      if (params.file_pattern) {
+        const glob = params.file_pattern.trim();
+        const quotedGlob = shQuote(glob);
+        let fileGrepOpts = grepOpts.replace(/--include(?:=\S+|\s+\S+)?/g, "").trim();
+
+        if (params.recursive === false) {
+          const namePred = glob.includes("*") || glob.includes("?") ? `-iname ${quotedGlob}` : `-name ${quotedGlob}`;
+          command = `find ${quotedPath} -maxdepth 1 -type f ${namePred} -exec grep -Hn ${fileGrepOpts} -e ${quotedPattern} {} + 2>&1`;
+        } else {
+          if (!/\s-r\b/.test(fileGrepOpts)) fileGrepOpts += " -r";
+          command = `grep ${fileGrepOpts} --include=${quotedGlob} -e ${quotedPattern} ${quotedPath} 2>&1`;
+        }
+      } else {
+        command = `grep ${grepOpts} -e ${quotedPattern} ${quotedPath} 2>&1`;
+      }
+      command += " || true";
+
+      const result = await execOnHPC(pi, command, { signal, timeout: GREP_TIMEOUT_MS });
+
+      if (result.killed) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `grep_hpc timed out after ${GREP_TIMEOUT_MS / 1000}s. Narrow the path, use file_pattern, or refine the pattern.`,
+            },
+          ],
+          details: { path: searchPath, pattern, timedOut: true, error: true },
+        };
+      }
+
+      if (isHpcFailure(result)) {
+        return {
+          content: [{ type: "text", text: formatHpcFailure(result) }],
+          details: {
+            path: searchPath,
+            pattern,
+            file_pattern: params.file_pattern,
+            exitCode: result.exitCode,
+            error: true,
+          },
+          isError: true,
+        };
+      }
+
+      const output = (result.stdout || "").trim();
+      const stderr = (result.stderr || "").trim();
+      if (!output) {
+        const scope = params.file_pattern ? `${searchPath} (files: ${params.file_pattern})` : searchPath;
+        if (stderr && /no such file|not found|cannot access/i.test(stderr)) {
+          return {
+            content: [{ type: "text", text: `grep_hpc failed:\n${stderr}` }],
+            details: { path: searchPath, pattern, error: true },
+            isError: true,
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No matches for ${JSON.stringify(pattern)} in ${scope}${grepOpts.includes("-E") ? " (extended regex)" : ""}`,
+            },
+          ],
+          details: {
+            path: searchPath,
+            pattern,
+            file_pattern: params.file_pattern,
+            matches: 0,
+            grepOptions: grepOpts,
+          },
+        };
+      }
+
+      const truncation = truncateHead(output, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let agentText = truncation.content;
+      const details: Record<string, unknown> = {
+        path: searchPath,
+        pattern,
+        grepOptions: grepOpts,
+        matches: output.split("\n").filter((l) => l.trim()).length,
+        exitCode: result.exitCode,
+      };
+
+      if (truncation.truncated) {
+        details.truncatedForAgent = true;
+        const omittedLines = truncation.totalLines - truncation.outputLines;
+        const omittedBytes = truncation.totalBytes - truncation.outputBytes;
+        agentText += ` |  [Output truncated for agent: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ${omittedLines} lines (${formatSize(omittedBytes)}) omitted. Narrow search path or pattern.]`;
+      }
+
+      return {
+        content: [{ type: "text", text: agentText }],
+        details,
+      };
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+export interface HPCConfig {
+  username: string;
+  host: string;
+  password: string;
+  plinkPath?: string;
+  enabledProjects?: string[];
+}
+
+export type HpcToolRenderResult = {
+  content: Array<{ type: string; text?: string }>;
+  details?: Record<string, unknown>;
+};
+
+export type HpcExecResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  killed?: boolean;
+};