@monotykamary/pi-localterm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aiden Bai
+
+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,71 @@
+# @monotykamary/pi-localterm
+
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension that integrates [localterm](https://github.com/monotykamary/localterm) with pi. Two features, both inert outside localterm:
+
+1. **Kitty graphics + OSC 8 links** — localterm renders xterm.js with the Kitty graphics and web-links addons loaded, but sets `TERM=xterm-256color` and strips terminal-identity env vars (so Ink TUIs don't probe for a protocol xterm.js lacks). pi-tui therefore reports images/hyperlinks as unsupported. This extension detects `LOCALTERM=1` (injected into every localterm PTY) and force-enables those capabilities, so images and links render in the browser.
+2. **Secret scrubbing for the agent's bash tool** — localterm injects a secret only into the shimmed process's env (pi's), not its parent shell. But pi's bash tool spawns commands with `{ ...process.env }`, so without this the agent's commands would inherit every secret pi received. This extension overrides the `bash` tool with a spawn hook that deletes the `pi` process's localterm-managed secret env vars from each command's child env only — pi's own `process.env` (and its provider calls) keep them.
+
+## Install
+
+From npm (published package):
+
+```bash
+pi install npm:@monotykamary/pi-localterm
+```
+
+From source (this monorepo, for a one-off run):
+
+```bash
+git clone https://github.com/monotykamary/localterm
+pi -e ./localterm/packages/pi-extension
+```
+
+<details>
+<summary>Manual install (load on every session)</summary>
+
+Clone and add the package to pi's global settings so it loads automatically:
+
+```bash
+git clone https://github.com/monotykamary/localterm ~/src/localterm
+```
+
+Then edit `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["/Users/you/src/localterm/packages/pi-extension"]
+}
+```
+
+Or, for a project-only install, add the same path to `<cwd>/.pi/settings.json` instead. Then `/reload` in pi.
+
+</details>
+
+The extension auto-activates only inside localterm (`LOCALTERM=1`); outside localterm it registers nothing and pi behaves exactly as default.
+
+## How the scrub works
+
+localterm stores secret **policy** (names + the env var each exports) in `~/.localterm/secrets.json` and per-process wiring (`pi` → which secret names it receives) in `~/.localterm/processes.json`. **Only names and env vars — never values** (values live in the macOS Keychain). The extension reads those two files to find the env-var names the `pi` process is wired to, and strips exactly those from each bash-tool child's environment.
+
+Resolution mirrors the shim 1:1: the shim injects the `pi` process's `requestedSecrets` (resolved to env vars); the scrub strips exactly that set. The strip set is recomputed on `session_start` (new / resume / fork / reload), so a policy change is picked up on the next session transition.
+
+This extends localterm's existing least-privilege property — "the shimmed binary sees the key, its parent shell doesn't" — to "pi sees the key, the agent's bash commands don't." It converts silent env inheritance into an explicit, greppable `localterm secret get <name>` call when an agent's command genuinely needs a key.
+
+## What this is not
+
+This is **defense-in-depth, not a security boundary**. The keys still live in pi's own `process.env`, so a command the agent generates can recover them via parent-process introspection (`ps eww $PPID` on macOS, `/proc/$PPID/environ` on Linux) or by shelling out to `security find-generic-password` directly (the shim's own resolution path). The scrub stops passive/accidental leakage (`env`, `printenv`, a script reading `$VAR`), not active exfiltration by a prompt-injected or adversarial agent.
+
+For untrusted or unmonitored agents, **don't wire secrets to the `pi` process at all** — give pi its provider keys through pi's own config, and run pi in a container/VM/micro-VM with short-lived credentials.
+
+## Overriding the bash tool
+
+The scrub overrides pi's built-in `bash` tool **by name** (extensions apply after the built-in in pi's tool registry). It reconstructs the tool via `createBashToolDefinition` and preserves a user's configured `shellPath` and `shellCommandPrefix` (read from `~/.pi/agent/settings.json` + `<cwd>/.pi/settings.json`) so the override is behavior-identical to the built-in apart from the env scrub. If another extension also overrides `bash`, only the first-registered one wins — that's a pi-level constraint.
+
+## Requirements
+
+- pi ≥ 0.80 (uses the `spawnHook` tool option and `createBashToolDefinition` export).
+- localterm with `LOCALTERM=1` in the PTY environment (v0.7+). The scrub additionally needs localterm's secrets/processes policy files on the same machine.
+
+## License
+
+MIT

package/extensions/bash-secret-scrub.ts

@@ -0,0 +1,38 @@
+import type { BashSpawnHook, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+import { readLocaltermSecretEnvVarsForPi } from "../src/utils/read-localterm-secret-policy.js";
+import { readPiShellSettings } from "../src/utils/read-pi-shell-settings.js";
+import { scrubEnv } from "../src/utils/scrub-env.js";
+
+// Strip localterm-managed secret env vars from the agent's bash-tool children.
+// The localterm shim injects each secret only into the shimmed process's env
+// (pi's), not its parent shell — but pi's bash tool spawns commands with
+// { ...process.env }, so without this the agent's commands inherit every secret
+// pi received (`env`, `printenv`, or any script could read a key). This
+// overrides the `bash` tool by name (extensions apply after the built-in in
+// pi's tool registry) with a spawnHook that deletes the pi process's secret
+// envVars from the child env only; pi's own process.env (and its provider
+// calls) keep them. The strip set is recomputed on session_start so a policy
+// change followed by /new, /resume, /fork, or /reload is picked up.
+//
+// This is defense-in-depth, NOT a hard barrier: a determined command can still
+// read the keys via parent-process introspection (`ps eww $PPID` on macOS,
+// `/proc/$PPID/environ` on Linux) or the Keychain directly. For untrusted or
+// unmonitored agents, don't wire secrets to the pi process at all.
+export const registerBashSecretScrub = (pi: ExtensionAPI): void => {
+  const cwd = process.cwd();
+  const { shellPath, commandPrefix } = readPiShellSettings(cwd);
+
+  let stripSet = new Set<string>(readLocaltermSecretEnvVarsForPi());
+  pi.on("session_start", () => {
+    stripSet = new Set(readLocaltermSecretEnvVarsForPi());
+  });
+
+  const spawnHook: BashSpawnHook = ({ command, cwd: spawnCwd, env }) => ({
+    command,
+    cwd: spawnCwd,
+    env: scrubEnv(env, stripSet),
+  });
+
+  pi.registerTool(createBashToolDefinition(cwd, { spawnHook, commandPrefix, shellPath }));
+};

package/extensions/index.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerBashSecretScrub } from "./bash-secret-scrub.js";
+import { registerKittyImages } from "./kitty-images.js";
+
+// localterm <-> pi integration, inert outside localterm. LOCALTERM=1 is
+// injected into every localterm PTY; when it's absent, nothing is registered
+// and pi behaves exactly as default. Inside localterm this (1) force-enables
+// Kitty graphics + OSC 8 links the xterm.js renderer supports but pi-tui can't
+// detect, and (2) scrubs localterm-managed secret env vars from the agent's
+// bash-tool children so a generated command can't read keys the shim injected
+// into pi's own env.
+export default (pi: ExtensionAPI): void => {
+  if (process.env.LOCALTERM !== "1") return;
+  registerKittyImages(pi);
+  registerBashSecretScrub(pi);
+};

package/extensions/kitty-images.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getCapabilities, setCapabilities } from "@earendil-works/pi-tui";
+
+// localterm renders xterm.js with the Kitty graphics + OSC 8 hyperlink addons
+// loaded, but sets TERM=xterm-256color and strips terminal-identity env vars so
+// Ink TUIs don't probe for a protocol xterm.js lacks. pi-tui therefore reports
+// images/hyperlinks as unsupported. localterm injects LOCALTERM=1 into the PTY
+// env; force-enable the capabilities the rendering layer actually supports so
+// images render instead of falling back to degraded inline text. Skips when
+// images are already enabled (e.g. pi nested inside a real Kitty terminal).
+export const registerKittyImages = (pi: ExtensionAPI): void => {
+  pi.on("session_start", async () => {
+    if (process.env.LOCALTERM !== "1") return;
+    const capabilities = getCapabilities();
+    if (capabilities.images) return;
+    setCapabilities({ ...capabilities, images: "kitty", hyperlinks: true });
+  });
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@monotykamary/pi-localterm",
+  "version": "0.1.0",
+  "description": "localterm <-> pi integration: Kitty graphics for the browser renderer, and scrubbing localterm-managed secret env vars from the agent's bash-tool children.",
+  "keywords": [
+    "localterm",
+    "pi",
+    "pi-package",
+    "secrets"
+  ],
+  "homepage": "https://github.com/monotykamary/localterm#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/localterm/issues"
+  },
+  "license": "MIT",
+  "author": "Aiden Bai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/localterm.git",
+    "directory": "packages/pi-extension"
+  },
+  "files": [
+    "extensions",
+    "src"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vp test --run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,24 @@
+// localterm's state directory and the two policy files the scrub reads. These
+// hold names + env vars only — NEVER secret values (values live in the macOS
+// Keychain) — so reading them never touches a key. Mirrors the same constants
+// in localterm-server so the paths stay in lockstep.
+export const LOCALTERM_STATE_DIRNAME = ".localterm";
+export const SECRETS_FILENAME = "secrets.json";
+export const PROCESSES_FILENAME = "processes.json";
+
+// The process name localterm wraps with a PATH shim. The scrub strips exactly
+// the secrets this process is wired to, mirroring what the shim injected.
+export const PI_PROCESS_NAME = "pi";
+
+// pi's settings file name (global ~/.pi/agent/settings.json + project
+// <cwd>/.pi/settings.json). The bash override reads these to preserve a
+// user's configured shell + command prefix.
+export const PI_SETTINGS_FILENAME = "settings.json";
+
+// Canonical validation patterns — mirror localterm-server's zod schemas so a
+// malformed or hostile policy file can never trick the scrub into deleting an
+// unrelated env var. An env var in particular must match the strict uppercase
+// identifier shape a real secret envVar always has.
+export const SECRET_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export const PROCESS_NAME_PATTERN = /^[A-Za-z0-9_.+-]+$/;
+export const ENV_VAR_PATTERN = /^[A-Z_][A-Z0-9_]*$/;

package/src/utils/read-localterm-secret-policy.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  ENV_VAR_PATTERN,
+  LOCALTERM_STATE_DIRNAME,
+  PI_PROCESS_NAME,
+  PROCESSES_FILENAME,
+  PROCESS_NAME_PATTERN,
+  SECRET_NAME_PATTERN,
+  SECRETS_FILENAME,
+} from "../constants.js";
+
+interface SecretEntry {
+  name: string;
+  envVar: string;
+}
+
+interface ProcessEntry {
+  name: string;
+  requestedSecrets: string[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const readJsonFile = (filePath: string): unknown => {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+const parseSecretsFile = (data: unknown): SecretEntry[] => {
+  if (!isRecord(data) || !Array.isArray(data.secrets)) return [];
+  return data.secrets
+    .filter(isRecord)
+    .map((entry) => ({ name: String(entry.name ?? ""), envVar: String(entry.envVar ?? "") }))
+    .filter((entry) => SECRET_NAME_PATTERN.test(entry.name) && ENV_VAR_PATTERN.test(entry.envVar));
+};
+
+const parseProcessesFile = (data: unknown): ProcessEntry[] => {
+  if (!isRecord(data) || !Array.isArray(data.processes)) return [];
+  return data.processes
+    .filter(isRecord)
+    .map((entry) => ({
+      name: String(entry.name ?? ""),
+      requestedSecrets: Array.isArray(entry.requestedSecrets)
+        ? entry.requestedSecrets.filter((item): item is string => typeof item === "string")
+        : [],
+    }))
+    .filter((entry) => PROCESS_NAME_PATTERN.test(entry.name));
+};
+
+// Resolve the env-var names localterm's shim injected into the `pi` process:
+// the pi process's requestedSecrets (processes.json), each mapped to its
+// envVar (secrets.json). These are the names to strip from pi's bash-tool
+// child env. Reads names + envVars only — NEVER secret values (those live in
+// the Keychain, never in these files). Tolerates missing or malformed files
+// (returns []) so a broken or absent localterm install degrades to a no-op
+// scrub rather than crashing the agent's bash tool. `stateDirectory` defaults
+// to the real ~/.localterm and is overridable for tests.
+export const readLocaltermSecretEnvVarsForPi = (
+  stateDirectory: string = join(homedir(), LOCALTERM_STATE_DIRNAME),
+): string[] => {
+  const secretsData = readJsonFile(join(stateDirectory, SECRETS_FILENAME));
+  const processesData = readJsonFile(join(stateDirectory, PROCESSES_FILENAME));
+
+  const envVarBySecretName = new Map<string, string>();
+  for (const secret of parseSecretsFile(secretsData)) {
+    envVarBySecretName.set(secret.name, secret.envVar);
+  }
+
+  const piProcess = parseProcessesFile(processesData).find(
+    (entry) => entry.name === PI_PROCESS_NAME,
+  );
+  if (!piProcess) return [];
+
+  const envVars: string[] = [];
+  for (const secretName of piProcess.requestedSecrets) {
+    if (!SECRET_NAME_PATTERN.test(secretName)) continue;
+    const envVar = envVarBySecretName.get(secretName);
+    if (envVar) envVars.push(envVar);
+  }
+  return envVars;
+};

package/src/utils/read-pi-shell-settings.ts

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { PI_SETTINGS_FILENAME } from "../constants.js";
+
+interface ShellSettings {
+  shellPath: string | undefined;
+  commandPrefix: string | undefined;
+}
+
+interface ShellSettingsPaths {
+  globalSettingsPath?: string;
+  configDirName?: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const readJsonFile = (filePath: string): Record<string, unknown> => {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+
+const readNonEmptyString = (settings: Record<string, unknown>, key: string): string | undefined => {
+  const value = settings[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+
+// Resolve the two shell settings pi's built-in bash tool bakes in at
+// construction — `shellPath` (override the shell binary) and
+// `shellCommandPrefix` (prepended to every command, e.g. "shopt -s
+// expand_aliases"). This extension overrides the `bash` tool by name to inject
+// a spawnHook, so it reconstructs the tool — and must pass these through
+// unchanged, or a user who configured them silently loses them. Reads the same
+// two files pi's SettingsManager merges (global ~/.pi/agent/settings.json +
+// project <cwd>/.pi/settings.json); project wins. A shallow merge suffices
+// because both keys are top-level scalars. `paths` is overridable for tests so
+// they never touch the real pi settings.
+export const readPiShellSettings = (cwd: string, paths: ShellSettingsPaths = {}): ShellSettings => {
+  const globalSettingsPath = paths.globalSettingsPath ?? join(getAgentDir(), PI_SETTINGS_FILENAME);
+  const configDirName = paths.configDirName ?? CONFIG_DIR_NAME;
+  const merged: Record<string, unknown> = {
+    ...readJsonFile(globalSettingsPath),
+    ...readJsonFile(join(cwd, configDirName, PI_SETTINGS_FILENAME)),
+  };
+  return {
+    shellPath: readNonEmptyString(merged, "shellPath"),
+    commandPrefix: readNonEmptyString(merged, "shellCommandPrefix"),
+  };
+};

package/src/utils/scrub-env.ts

@@ -0,0 +1,13 @@
+// Remove the given env-var names from an environment object, returning a new
+// object (the input is never mutated). The bash spawnHook uses this to strip
+// localterm-managed secret env vars from the child process's environment so a
+// command the agent generates cannot read keys the localterm shim injected into
+// pi's own env. Pure: unit-testable without spawning a process.
+export const scrubEnv = (env: NodeJS.ProcessEnv, strip: ReadonlySet<string>): NodeJS.ProcessEnv => {
+  if (strip.size === 0) return env;
+  const next: NodeJS.ProcessEnv = { ...env };
+  for (const name of strip) {
+    if (Object.prototype.hasOwnProperty.call(next, name)) delete next[name];
+  }
+  return next;
+};