pi-term 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jainam Bhavasar
+
+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

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# pi-term
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Background terminals for [pi](https://pi.dev).
+
+![pi-term demo](https://raw.githubusercontent.com/jainam-bhavasar/pi-term/main/docs/demo.gif)
+
+`bash` tool calls end when the command ends. That breaks for anything that has to keep running: dev servers, `flutter run`, REPLs, watchers, log tails. pi-term gives the agent named tmux sessions it can start, read and type into, without blocking the conversation.
+
+```bash
+pi install npm:pi-term
+```
+
+Requires `tmux` (`brew install tmux` or `apt install tmux`).
+
+## What you get
+
+**`term` tool for the agent**
+
+| action | does |
+|---|---|
+| `start` | start `pi-<name>` in a directory, optionally running a command. Never restarts an existing session. |
+| `read` | capture the last N lines of output |
+| `send` | type input, with or without Enter (e.g. `r` for Flutter hot reload) |
+| `list` | list `pi-` sessions |
+| `kill` | stop a session |
+| `open` | open the session in a terminal window for you |
+
+**`/term` command for you**
+
+- `/term` lists running sessions and opens the one you pick
+- `/term <name>` opens `pi-<name>`, creating it if needed
+
+On macOS it opens Ghostty, falling back to Terminal.app. On other systems it prints the `tmux attach` command to run.
+
+**`term` skill** that tells the agent when to use `term` instead of `bash`.
+
+## Cleanup
+
+Every session records the pid of the pi process that created it. Quitting pi, `/new`, `/resume` or forking kills that process's sessions; `/reload` keeps them. If pi dies without a clean exit, the next pi start kills the leftovers. Sessions you start yourself without the `pi-` owner tag are never touched.
+
+## Example
+
+> start the web dev server and tell me when it's ready
+
+```json
+{ "action": "start", "name": "web", "command": "npm run dev" }
+{ "action": "read", "name": "web" }
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,116 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	hasSession,
+	killOrphanedSessions,
+	killOwnedSessions,
+	killSession,
+	listSessions,
+	openViewer,
+	readSession,
+	sendSession,
+	sessionName,
+	startSession,
+} from "./tmux.ts";
+
+export default function termExtension(pi: ExtensionAPI) {
+	// Terminals live as long as the pi session that started them.
+	pi.on("session_start", async () => {
+		await killOrphanedSessions();
+	});
+	pi.on("session_shutdown", async (event) => {
+		// reload keeps the same session and process, so keep its terminals running
+		if (event.reason === "reload") return;
+		await killOwnedSessions();
+	});
+
+	pi.registerTool({
+		name: "term",
+		label: "Terminal",
+		description:
+			"Run a long-lived interactive program in a named tmux session. The call returns immediately. Read output later and send keys without attaching.",
+		promptSnippet: "Start, read, type into, list, or stop a background tmux terminal",
+		promptGuidelines: [
+			"Use term instead of bash when a command must keep running after the call returns, such as flutter run, a dev server, a REPL, or a log stream.",
+			"Use term action read to inspect a session. Do not assume the first read contains the final result.",
+			"Use term action send to type into a session. Never tmux attach from bash; attach blocks and dies when the tool call ends.",
+			"Do not start a new command in a session that already exists. term start reports the existing session instead of restarting it.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(["start", "read", "send", "list", "kill", "open"] as const),
+			name: Type.Optional(Type.String({ description: "Session name. Stored as pi-<name>." })),
+			command: Type.Optional(Type.String({ description: "Command to type into a new session. Ignored if the session exists." })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for a new session. Defaults to the project cwd." })),
+			input: Type.Optional(Type.String({ description: "Text to type for action send." })),
+			submit: Type.Optional(Type.Boolean({ description: "Press Enter after input. Default true." })),
+			lines: Type.Optional(Type.Number({ description: "Scrollback lines to capture. Default 200." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const cwd = params.cwd || ctx.cwd;
+			switch (params.action) {
+				case "list": {
+					const sessions = await listSessions();
+					return {
+						content: [{ type: "text", text: sessions.length ? sessions.join("\n") : "No pi- terminals." }],
+						details: { sessions },
+					};
+				}
+				case "start": {
+					if (!params.name) throw new Error("name is required");
+					const text = await startSession(params.name, cwd, params.command);
+					return { content: [{ type: "text", text }], details: { session: sessionName(params.name) } };
+				}
+				case "read": {
+					if (!params.name) throw new Error("name is required");
+					const text = await readSession(params.name, params.lines ?? 200);
+					return { content: [{ type: "text", text }], details: { session: sessionName(params.name) } };
+				}
+				case "send": {
+					if (!params.name) throw new Error("name is required");
+					const text = await sendSession(params.name, params.input ?? "", params.submit !== false);
+					const output = await readSession(params.name, 40);
+					return { content: [{ type: "text", text: `${text}\n\n${output}` }], details: {} };
+				}
+				case "kill": {
+					if (!params.name) throw new Error("name is required");
+					return { content: [{ type: "text", text: await killSession(params.name) }], details: {} };
+				}
+				case "open": {
+					if (!params.name) throw new Error("name is required");
+					return { content: [{ type: "text", text: await openViewer(params.name) }], details: {} };
+				}
+			}
+		},
+	});
+
+	pi.registerCommand("term", {
+		description: "List background terminals, or open one in Ghostty: /term <name>",
+		getArgumentCompletions: async (prefix) => {
+			const sessions = await listSessions();
+			const items = sessions
+				.map((session) => session.replace(/^pi-/, ""))
+				.filter((name) => name.startsWith(prefix))
+				.map((name) => ({ value: name, label: name }));
+			return items.length ? items : null;
+		},
+		handler: async (args, ctx) => {
+			const name = args.trim().split(/\s+/)[0];
+			if (!name) {
+				const sessions = await listSessions();
+				if (sessions.length === 0) {
+					ctx.ui.notify("No pi- terminals. Ask pi to term start one.", "info");
+					return;
+				}
+				const picked = await ctx.ui.select("Background terminals", sessions);
+				if (!picked) return;
+				ctx.ui.notify(await openViewer(picked.replace(/^pi-/, "")), "info");
+				return;
+			}
+			if (!(await hasSession(name))) {
+				await startSession(name, ctx.cwd);
+			}
+			ctx.ui.notify(await openViewer(name), "info");
+		},
+	});
+}

package/extensions/tmux.ts

@@ -0,0 +1,184 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+
+export function sessionName(name: string): string {
+	if (!NAME_RE.test(name)) {
+		throw new Error(`Invalid terminal name "${name}". Use letters, digits, "-" and "_" only.`);
+	}
+	return name.startsWith("pi-") ? name : `pi-${name}`;
+}
+
+async function tmuxBin(): Promise<string> {
+	const candidates = [process.env.TMUX_BIN, "/opt/homebrew/bin/tmux", "/usr/local/bin/tmux", "tmux"].filter(
+		(value): value is string => Boolean(value),
+	);
+	for (const bin of candidates) {
+		try {
+			await execFileAsync(bin, ["-V"]);
+			return bin;
+		} catch {
+			// try the next candidate
+		}
+	}
+	throw new Error("tmux is not installed. Install it with: brew install tmux");
+}
+
+async function tmux(args: string[], cwd?: string): Promise<string> {
+	const bin = await tmuxBin();
+	try {
+		const { stdout, stderr } = await execFileAsync(bin, args, {
+			cwd,
+			maxBuffer: 1024 * 1024,
+		});
+		return `${stdout}${stderr}`.trimEnd();
+	} catch (error) {
+		const err = error as { stdout?: string; stderr?: string; message?: string; code?: number };
+		const detail = `${err.stderr ?? ""}${err.stdout ?? ""}`.trim();
+		if (err.code === 1 && args[0] === "has-session") return "";
+		throw new Error(detail || err.message || "tmux failed");
+	}
+}
+
+export async function hasSession(name: string): Promise<boolean> {
+	const bin = await tmuxBin();
+	try {
+		await execFileAsync(bin, ["has-session", "-t", sessionName(name)]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function listSessions(): Promise<string[]> {
+	try {
+		const out = await tmux(["list-sessions", "-F", "#{session_name}"]);
+		return out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line.startsWith("pi-"));
+	} catch {
+		return [];
+	}
+}
+
+// Each session records the pid of the pi process that created it in the
+// tmux user option @pi_owner, so pi can clean up after itself on exit.
+const OWNER_OPT = "@pi_owner";
+
+async function newSession(target: string, cwd: string): Promise<void> {
+	await tmux(["new-session", "-d", "-s", target, "-c", cwd]);
+	await tmux(["set-option", "-t", target, OWNER_OPT, String(process.pid)]);
+}
+
+async function sessionsWithOwner(): Promise<{ name: string; owner: number | null }[]> {
+	try {
+		const out = await tmux(["list-sessions", "-F", `#{session_name}\t#{${OWNER_OPT}}`]);
+		return out
+			.split("\n")
+			.map((line) => line.trim().split("\t"))
+			.filter(([name]) => name?.startsWith("pi-"))
+			.map(([name, owner]) => ({ name, owner: owner && /^\d+$/.test(owner) ? Number(owner) : null }));
+	} catch {
+		return [];
+	}
+}
+
+function pidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Kill every pi- session created by this pi process. Idempotent. */
+export async function killOwnedSessions(): Promise<string[]> {
+	const mine = (await sessionsWithOwner()).filter((s) => s.owner === process.pid);
+	for (const s of mine) await tmux(["kill-session", "-t", s.name]).catch(() => {});
+	return mine.map((s) => s.name);
+}
+
+/** Kill pi- sessions whose owning pi process is gone (e.g. it crashed or the window was closed). */
+export async function killOrphanedSessions(): Promise<string[]> {
+	const orphans = (await sessionsWithOwner()).filter((s) => s.owner !== null && s.owner !== process.pid && !pidAlive(s.owner));
+	for (const s of orphans) await tmux(["kill-session", "-t", s.name]).catch(() => {});
+	return orphans.map((s) => s.name);
+}
+
+export async function startSession(name: string, cwd: string, command?: string): Promise<string> {
+	const target = sessionName(name);
+	if (await hasSession(name)) {
+		return `exists ${target}\n${await readSession(name, 80)}`;
+	}
+	await newSession(target, cwd);
+	if (command?.trim()) {
+		await tmux(["send-keys", "-t", target, "-l", "--", command]);
+		await tmux(["send-keys", "-t", target, "Enter"]);
+	}
+	return `started ${target}${command?.trim() ? `\n$ ${command}` : ""}`;
+}
+
+export async function readSession(name: string, lines = 200): Promise<string> {
+	const target = sessionName(name);
+	if (!(await hasSession(name))) throw new Error(`No session ${target}`);
+	const text = await tmux(["capture-pane", "-p", "-t", target, "-S", `-${Math.max(1, lines)}`]);
+	return text.trim() ? text : `(${target} is empty)`;
+}
+
+export async function sendSession(name: string, input: string, submit = true): Promise<string> {
+	const target = sessionName(name);
+	if (!(await hasSession(name))) throw new Error(`No session ${target}`);
+	if (input) await tmux(["send-keys", "-t", target, "-l", "--", input]);
+	if (submit) await tmux(["send-keys", "-t", target, "Enter"]);
+	return `sent to ${target}`;
+}
+
+export async function killSession(name: string): Promise<string> {
+	const target = sessionName(name);
+	await tmux(["kill-session", "-t", target]);
+	return `killed ${target}`;
+}
+
+async function attachScript(target: string): Promise<string> {
+	const dir = join(homedir(), ".pi", "agent", "pi-term");
+	await mkdir(dir, { recursive: true });
+	const path = join(dir, `attach-${target}.sh`);
+	// Ghostty runs `-e` through /usr/bin/login, which execs that string as one path.
+	// A shebang script is a real executable and can see Homebrew's tmux.
+	const body = [
+		"#!/bin/zsh",
+		"export PATH=\"/opt/homebrew/bin:/usr/local/bin:$PATH\"",
+		`exec tmux attach -t ${JSON.stringify(target)}`,
+		"",
+	].join("\n");
+	await writeFile(path, body);
+	await chmod(path, 0o755);
+	return path;
+}
+
+export async function openViewer(name: string): Promise<string> {
+	const target = sessionName(name);
+	if (!(await hasSession(name))) {
+		await newSession(target, process.cwd());
+	}
+	if (process.platform !== "darwin") {
+		return `run in another terminal: tmux attach -t ${target}`;
+	}
+	const script = await attachScript(target);
+	try {
+		await execFileAsync("open", ["-na", "Ghostty.app", "--args", "-e", script]);
+		return `opened Ghostty on ${target}`;
+	} catch {
+		const command = `export PATH=\"/opt/homebrew/bin:$PATH\"; tmux attach -t ${target}`;
+		await execFileAsync("osascript", ["-e", `tell application \"Terminal\" to do script ${JSON.stringify(command)}`]);
+		return `opened Terminal on ${target}`;
+	}
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "pi-term",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Background terminals for pi: let the agent start, read and type into long-running programs (dev servers, flutter run, REPLs, log tails) in named tmux sessions.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jainam Bhavasar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jainam-bhavasar/pi-term.git"
+  },
+  "homepage": "https://github.com/jainam-bhavasar/pi-term#readme",
+  "bugs": "https://github.com/jainam-bhavasar/pi-term/issues",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "tmux",
+    "terminal",
+    "dev-server",
+    "coding-agent"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "image": "https://raw.githubusercontent.com/jainam-bhavasar/pi-term/main/docs/demo.gif",
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/skills/term/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: term
+description: Keep interactive programs running in named tmux sessions via the term tool. Use for dev servers, flutter run, REPLs, watchers and log streams that must outlive a single shell call.
+---
+
+# term
+
+Long-running programs go through the `term` tool, not `bash`. A session is `pi-<name>` and keeps running between tool calls until pi exits.
+
+## Actions
+
+- `start` with `name`, optional `command`, optional `cwd`. If the session exists, it is not restarted.
+- `read` with `name` and optional `lines`. Poll until the output you need appears.
+- `send` with `name` and `input`. Set `submit: false` for a single key such as Flutter hot reload `r`.
+- `list`, `kill`, `open`.
+
+`open` shows the session in a terminal window so the user can watch or type. Do not `tmux attach` yourself.
+
+## Example
+
+Start a dev server, then read it:
+
+```json
+{ "action": "start", "name": "web", "command": "npm run dev", "cwd": "/path/to/project" }
+```
+
+```json
+{ "action": "read", "name": "web", "lines": 120 }
+```
+
+Hot reload a running Flutter app:
+
+```json
+{ "action": "send", "name": "app", "input": "r", "submit": false }
+```