pi-friends 0.0.0-stage → 1.0.0

package/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md: pi-friends
+
+Purpose and design: `README.md`. Public repo (nkavassalis), personal project, MIT.
+
+Rules:
+- **Public-safe, always.** Never commit IPs, hostnames, usernames, home paths, keys or live config.
+  Hosts and keys live in an untracked `.env` or in `~/.config/pi-friends/`. This repo gets installed
+  by strangers; assume every line is read by someone who is not Nick.
+- Never hardcode a friend's name, endpoint or model into code. Friends are config; the only place a
+  specific friend may appear is `scripts/install-flint.sh` (it provisions one named example) and the
+  README, where it is labelled as a measured example rather than a requirement.
+- Every claim about quality or speed is measured, with the result file next to it, or labelled unmeasured.
+- Don't change how any server runs here: serving belongs to spark-tuning and mac-tuning.
+- Dates YYYY-MM-DD; date every statement of current state.
+
+## Layout
+| Path | What |
+|---|---|
+| `package.json` | npm/pi package manifest; the `pi-package` keyword is what makes it discoverable in the pi gallery |
+| `extensions/friends/index.ts` | the pi extension: registers one `ask_<name>` tool per configured friend, plus `/friends` |
+| `extensions/friends/client.ts` | config (legacy + `friends[]` shapes), per-friend one-at-a-time queue, the streamed request, brief check (no pi imports) |
+| `extensions/friends/tunnel.ts` | optional on-demand SSH tunnel (used only with a `tunnel` config block) |
+| `test/client.test.ts`, `test/tunnel.test.ts`, `test/fake_ssh.mjs` | offline tests: fake OpenAI-compatible SSE server, fake ssh |
+| `scripts/tunnel-flint.sh` | manual alternative: loopback-only SSH tunnel to the Mac, self-restarting |
+| `scripts/install-flint.sh [--uninstall]` | provisions the flint example: symlink, key, default config |
+
+## Tests (run before every commit)
+```bash
+node --experimental-strip-types --test test/*.test.ts
+bash -n scripts/*.sh
+git diff --cached | grep -nE '([0-9]{1,3}\.){3}[0-9]{1,3}|/home/|/Users/|hf_[A-Za-z0-9]{10,}|gh[pousr]_[A-Za-z0-9]{10,}'   # 127.0.0.1 is fine
+```
+Run pi from scripts with `< /dev/null`: piped stdin becomes part of the prompt.
+
+## Notes for agents
+- `client.ts` must stay importable without pi (that is what makes the tests offline); all pi
+  imports live in `index.ts`.
+- A friend's server is assumed single-generation, so `Queue` is per friend, not global — two
+  different servers should not serialize against each other.
+- `loadFriends()` re-reads the file on every call (config edits need no restart) but tools register
+  once at startup, so adding a friend needs a pi restart; changing its `baseUrl` does not.
+- The pre-rename config dir `~/.config/pi-escalation/` is still read as a fallback
+  (`resolveCfg`); remove that fallback once no install uses it (dated 2026-10-29).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Kavassalis
+
+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,105 @@
-# Temporary Holding Version
+# pi-friends
 
-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.
+A [pi](https://pi.dev/) extension for consulting **other models on hard problems** — without ever
+handing them your session. Each *friend* is any OpenAI-compatible chat endpoint; each gets its own
+`ask_<name>` tool. The agent writes a self-contained brief, the friend sees **only the brief** (no
+conversation history, no files), and only the final answer comes back.
+
+```json
+{ "friends": [
+  { "name": "flint", "baseUrl": "http://<reasoning-box>:11502/v1", "model": "flint" },
+  { "name": "sage",  "baseUrl": "http://<review-box>:8000/v1",  "model": "sage",
+    "system": "You review plans. Answer with flaws ranked by severity." }
+]}
+```
+→ tools `ask_flint` and `ask_sage`, each with its own queue, persona, description and key file.
+Adding a friend is a config entry plus a key file — no code.
+
+## Why this shape
+
+Big-model escalation usually means switching the session's model, which re-sends the whole
+conversation. That is slow (prefill dominates on small hardware), leaks the entire history to a
+third endpoint, and pollutes the friend's context with tool-call noise. Friends invert it:
+
+- **One turn, brief only.** The friend prefills ~1–16K tokens you *chose*, not 100K you didn't.
+- **Answer, not transcript.** Reasoning tokens are counted for stats but never returned; the agent
+  gets the solution, applies it, and runs the tests. (Verification is the agent's job — a friend's
+  answer is a strong suggestion, not authority.)
+- **Good briefs are a skill, so the tool teaches it.** The tool description tells the agent what a
+  brief must contain (goal, code pasted, failing output, constraints, what was tried) and refuses
+  briefs over `maxBriefChars` instead of silently truncating them.
+- **Per-friend queues with progress.** Local servers (llama.cpp, rec, vLLM single-worker) serve one
+  generation at a time; the tool serializes and reports "waiting for N earlier call(s)".
+
+A measured example of the trade-off (same problems, seeds and sandbox on both machines; details in
+[spark-tuning](https://github.com/nkavassalis/spark-tuning) and
+[mac-tuning](https://github.com/nkavassalis/mac-tuning)): a local agent model (Qwen FP4, 2× GB10)
+solves ~51% of hard LiveCodeBench problems; a reasoning model on a Mac mini (Recursive Flint int4)
+solves ~71% of the same set — and solves almost everything the agent model solves. Routing the hard
+problems to the friend beat racing both models. **Your numbers will differ; measure before you
+trust any friend.** Flint's edge is measured on competitive programming; its use as a *design
+reviewer* (which the tool also supports) is promising but unmeasured.
+
+## Install
+
+```bash
+pi install git:github.com/nkavassalis/pi-friends@v1.0.0     # or npm: pi install npm:pi-friends
+# or from a clone, for development:
+pi --extension extensions/friends/index.ts                  # one run, nothing installed globally
+```
+
+Then write `~/.config/pi-friends/config.json` (see the shape above) and a key file per friend that
+auths: `~/.config/pi-friends/<name>_key` (mode 600; contents never displayed by anything here).
+`/friends` inside pi lists configured friends — tool, endpoint, model, key status, tunnel/direct.
+Config is re-read per call, so `baseUrl`/key edits take effect without a restart; a **new friend**
+needs a pi restart (tools register at startup).
+
+If you host Flint with [Recursive's `rec`](https://github.com/recursive-org) on a Mac,
+`scripts/install-flint.sh` provisions that one friend (fetches the key over SSH, writes the config);
+`scripts/tunnel-flint.sh` is the manual SSH-tunnel fallback. Everything else in this repo is
+friend-agnostic.
+
+## Settings
+
+`~/.config/pi-friends/config.json` — either `{"friends":[{...}, ...]}` or a single friend inline
+(legacy shape; loads as one friend named `friend`). Unknown keys are passed through; missing keys
+take the defaults in `client.ts`.
+
+| Setting | Default | Notes |
+|---|---|---|
+| `name` | `friend` | tool becomes `ask_<name>` (sanitized to `[a-z0-9_]`) |
+| `baseUrl` | `http://127.0.0.1:11501/v1` | OpenAI-compatible base URL |
+| `model` | `friend` | sent as `model` in the request |
+| `keyFile` | `~/.config/pi-friends/<name>_key` | bearer token; read at call time, never logged |
+| `system` | built-in | one-turn persona; set per friend (e.g. reviewer vs solver) |
+| `description` / `label` / `guidelines` | built-in | override the tool's prompt text; `{{tool}}` is substituted |
+| `maxTokens` | 32768 | reasoning **and** answer share this; reasoning-only exhaustion is reported as such |
+| `temperature` / `topP` / `topK` | 0.6 / 0.95 / 20 | the measured-best setting for flint; tune per friend |
+| `timeoutMin` | 20 | whole request, queue wait excluded |
+| `maxBriefChars` | 64000 | longer briefs are refused with advice, never truncated |
+| `tunnel` | unset | optional `{host, identity, localPort, remotePort}`: the tool opens/repairs a loopback `ssh -N -L` itself — for friends on machines that aren't always reachable |
+
+## Privacy & safety
+
+- The friend receives **only** the brief and the system persona. No session history, no file paths
+  unless the agent pasted them, no environment variables.
+- Keys live in 600-mode files and are read at call time; nothing prints their contents.
+- Briefs travel as plain HTTP by default — fine on a trusted LAN, put TLS or a tunnel in front of
+  anything else. Treat anything in a brief as disclosed to that endpoint's operator.
+- The tool refuses empty and oversized briefs; it never silently cuts.
+
+## Tests
+
+```bash
+node --experimental-strip-types --test test/*.test.ts   # offline: fake OpenAI-compatible SSE server + fake ssh
+bash -n scripts/*.sh
+```
+
+16 tests cover streaming (reasoning in `delta.reasoning`, answer in `delta.content`, usage in the
+final empty-choices chunk), request shape and auth headers, timeouts, abort, the queue, the brief
+limit, config loading (legacy + friends shapes, name sanitizing, per-name key defaults) and the
+tunnel state machine.
+
+## License
+
+MIT

package/extensions/friends/client.ts

@@ -0,0 +1,210 @@
+// Friend client: config, a one-at-a-time queue, and one streamed chat request.
+// No pi imports, so `node --test` can run it (test/client.test.ts) against a fake server.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { TunnelConfig } from "./tunnel.ts";
+
+export interface FriendConfig {
+	name?: string; // friend name; the tool is ask_<name>. Default "friend" (a legacy single-friend config loads as one friend named "friend")
+	baseUrl: string; // OpenAI-compatible base, e.g. http://<mac>:11502/v1 (mac-tuning's LAN relay in front of rec)
+	model: string;
+	keyFile: string; // file holding the server's API key
+	maxTokens: number; // reasoning + answer; reasoning models need a large budget
+	temperature: number;
+	topP: number;
+	topK: number;
+	timeoutMin: number; // whole request, queue wait excluded
+	maxBriefChars: number; // longer briefs are refused (slow hosts prefill ~600 tok/s), never cut
+	tunnel?: TunnelConfig; // set: the tool opens/repairs the SSH tunnel itself before each call (tunnel.ts)
+	system?: string; // persona for the one-turn chat (index.ts has a default)
+	description?: string; // tool description override
+	label?: string; // display name in the tool UI
+	guidelines?: string[]; // prompt-guideline overrides; {{tool}} is replaced with the tool name
+}
+
+export const DEFAULTS: FriendConfig = {
+	name: "friend",
+	baseUrl: "http://127.0.0.1:11501/v1",
+	model: "friend",
+	keyFile: "~/.config/pi-friends/friend_key",
+	maxTokens: 32768,
+	temperature: 0.6, // measured best for the flint friend (see README benchmarks)
+	topP: 0.95,
+	topK: 20,
+	timeoutMin: 20,
+	maxBriefChars: 64000, // ~16-18K tokens, ~30 s of prefill on a slow host
+};
+
+export const CONFIG_PATH = join(homedir(), ".config", "pi-friends", "config.json");
+const LEGACY_CONFIG_PATH = join(homedir(), ".config", "pi-escalation", "config.json"); // pre-rename location, read-fallback only
+
+/** New location wins; fall back to the pre-rename dir so a half-migrated box still works. */
+function resolveCfg(p: string): string {
+	return p === CONFIG_PATH && !existsSync(p) && existsSync(LEGACY_CONFIG_PATH) ? LEGACY_CONFIG_PATH : p;
+}
+
+const expand = (p: string) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+
+export function loadConfig(p = CONFIG_PATH): FriendConfig {
+	const path = resolveCfg(p);
+	let file: Partial<FriendConfig> = {};
+	try {
+		file = JSON.parse(readFileSync(path, "utf8"));
+	} catch (e: any) {
+		if (e?.code !== "ENOENT") throw new Error(`friends: cannot read ${path}: ${e.message}`);
+	}
+	return { ...DEFAULTS, ...file };
+}
+
+/**
+ * All friends to register. config.json is either the original single-friend shape
+ * (loads as one friend named "friend" — existing installs keep working) or
+ * {"friends":[{name, baseUrl, ...}, ...]}. Each named friend defaults its keyFile to
+ * ~/.config/pi-friends/<name>_key; names are sanitized to [a-z0-9_] so the tool
+ * name ask_<name> is always valid.
+ */
+export function loadFriends(p = CONFIG_PATH): FriendConfig[] {
+	const path = resolveCfg(p);
+	let file: any = {};
+	try {
+		file = JSON.parse(readFileSync(path, "utf8"));
+	} catch (e: any) {
+		if (e?.code !== "ENOENT") throw new Error(`friends: cannot read ${path}: ${e.message}`);
+	}
+	if (Array.isArray(file?.friends) && file.friends.length > 0) {
+		return file.friends.map((f: any) => {
+			const clean = String(f?.name ?? "friend").toLowerCase().replace(/[^a-z0-9_]/g, "_");
+			return { ...DEFAULTS, ...f, name: clean, keyFile: f.keyFile ?? `~/.config/pi-friends/${clean}_key` } as FriendConfig;
+		});
+	}
+	return [{ ...DEFAULTS, ...file }]; // legacy single-friend config
+}
+
+export function readKey(cfg: FriendConfig): string {
+	try {
+		return readFileSync(expand(cfg.keyFile), "utf8").trim();
+	} catch (e: any) {
+		throw new Error(`friends: cannot read the API key file ${cfg.keyFile}: ${e.message}`);
+	}
+}
+
+/** Runs tasks one at a time: most local servers serve a single generation, so parallel calls would only queue there blind. */
+export class Queue {
+	private tail: Promise<unknown> = Promise.resolve();
+	private pending = 0;
+	/** Calls queued or running. */
+	get length() {
+		return this.pending;
+	}
+	run<T>(task: () => Promise<T>): Promise<T> {
+		this.pending++;
+		const go = () => task().finally(() => this.pending--);
+		const next = this.tail.then(go, go);
+		this.tail = next.catch(() => undefined);
+		return next;
+	}
+}
+
+export interface FriendResult {
+	answer: string;
+	reasoningChars: number;
+	finish: string; // "stop" | "length" | ...
+	promptTokens: number;
+	completionTokens: number;
+	cachedTokens: number;
+	seconds: number;
+}
+
+export type Progress = (p: { seconds: number; reasoningChars: number; answerChars: number }) => void;
+
+/** One fresh single-turn chat: the brief is the whole context, no session history. Streams so long reasoning never hits a
+ *  header timeout; reasoning is counted, not returned. */
+export async function askFriend(
+	cfg: FriendConfig,
+	key: string,
+	brief: string,
+	signal?: AbortSignal,
+	onProgress?: Progress,
+	system?: string,
+): Promise<FriendResult> {
+	const t0 = Date.now();
+	const timeout = AbortSignal.timeout(cfg.timeoutMin * 60_000);
+	const sig = signal ? AbortSignal.any([signal, timeout]) : timeout;
+	const messages = [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: brief }];
+	let res: Response;
+	try {
+		res = await fetch(`${cfg.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+			body: JSON.stringify({
+				model: cfg.model,
+				messages,
+				stream: true,
+				stream_options: { include_usage: true },
+				max_tokens: cfg.maxTokens,
+				temperature: cfg.temperature,
+				top_p: cfg.topP,
+				top_k: cfg.topK,
+			}),
+			signal: sig,
+		});
+	} catch (e: any) {
+		throw new Error(timeout.aborted ? `friends: timed out after ${cfg.timeoutMin} min` : `friends: cannot reach ${cfg.name ?? "friend"} at ${cfg.baseUrl} (is the server up, and is baseUrl right?): ${e.message}`);
+	}
+	if (!res.ok || !res.body) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`friends: ${cfg.name ?? "friend"} answered HTTP ${res.status}: ${text.slice(0, 300)}`);
+	}
+	let answer = "", reasoningChars = 0, finish = "", buf = "", lastTick = 0;
+	let usage: any = {};
+	const dec = new TextDecoder();
+	try {
+		for await (const chunk of res.body as any) {
+			buf += dec.decode(chunk, { stream: true });
+			let nl: number;
+			while ((nl = buf.indexOf("\n")) >= 0) {
+				const line = buf.slice(0, nl).trim();
+				buf = buf.slice(nl + 1);
+				if (!line.startsWith("data:")) continue;
+				const data = line.slice(5).trim();
+				if (data === "[DONE]") continue;
+				const ev = JSON.parse(data);
+				if (ev.usage) usage = ev.usage;
+				for (const ch of ev.choices ?? []) {
+					const d = ch.delta ?? {};
+					if (typeof d.content === "string") answer += d.content;
+					const r = d.reasoning ?? d.reasoning_content;
+					if (typeof r === "string") reasoningChars += r.length;
+					if (ch.finish_reason) finish = ch.finish_reason;
+				}
+			}
+			if (onProgress && Date.now() - lastTick > 2000) {
+				lastTick = Date.now();
+				onProgress({ seconds: (lastTick - t0) / 1000, reasoningChars, answerChars: answer.length });
+			}
+		}
+	} catch (e: any) {
+		if (timeout.aborted) throw new Error(`friends: timed out after ${cfg.timeoutMin} min (${reasoningChars} reasoning chars so far)`);
+		throw e;
+	}
+	return {
+		answer: answer.trim(),
+		reasoningChars,
+		finish: finish || "unknown",
+		promptTokens: usage.prompt_tokens ?? 0,
+		completionTokens: usage.completion_tokens ?? 0,
+		cachedTokens: usage.prompt_tokens_details?.cached_tokens ?? 0,
+		seconds: (Date.now() - t0) / 1000,
+	};
+}
+
+export function checkBrief(cfg: FriendConfig, brief: string): string | undefined {
+	if (!brief.trim()) return "friends: the brief is empty.";
+	if (brief.length > cfg.maxBriefChars)
+		return (
+			`friends: the brief is ${brief.length} characters, over the ${cfg.maxBriefChars} limit (the Mac prefills slowly). ` +
+			"Send only the code and context the problem needs, then call the tool again."
+		);
+	return undefined;
+}

package/extensions/friends/index.ts

@@ -0,0 +1,123 @@
+// friends: consult other models on hard, self-contained problems (or plans to review) from the session model to a "friend" —
+// another machine's model that sees ONLY the brief, never the conversation or the files. Friends are config:
+// ~/.config/pi-friends/config.json holds {"friends":[...]} or (legacy) one friend inline:
+// {"friends":[{name, baseUrl, model, keyFile, system?, description?, label?, guidelines?, maxTokens?, temperature?,
+// topP?, topK?, timeoutMin?, maxBriefChars?, tunnel?}, ...]}. Each friend registers its own ask_<name> tool with its
+// own queue (each server serves one generation at a time). Design and measurements: README.md.
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { askFriend, checkBrief, loadFriends, Queue, readKey, type FriendConfig } from "./client.ts";
+import { ensureTunnel } from "./tunnel.ts";
+
+const DEFAULT_SYSTEM =
+	"You are consulted by another coding agent on a hard problem. The brief below is all the context you have. " +
+	"Reason it through, then answer with the solution itself: the code (complete functions, not fragments) and a short " +
+	"explanation of the key idea and why it is correct. If the brief lacks something you need, say exactly what.";
+
+function makeTool(f: FriendConfig) {
+	const name = f.name ?? "friend";
+	const toolName = `ask_${name}`;
+	const label = f.label ?? name;
+	const queue = new Queue(); // per friend: separate servers, independent one-at-a-time slots
+
+	const description =
+		f.description ??
+		`Hand a hard, self-contained problem to ${label}. It sees ONLY the brief, not this conversation or the files, so the ` +
+		`brief must contain everything: the goal, the relevant code, the exact failing test or error output, constraints ` +
+		`(language, signatures, limits) and what was already tried. Also useful as a design reviewer: send the plan plus its ` +
+		`constraints and invariants and ask for flaws ranked by severity. Slow: expect 1-10 minutes. Returns the answer; ` +
+		`verify it (apply it, run the tests) before relying on it.`;
+
+	const guidelines = (
+		f.guidelines ?? [
+			"Use {{tool}} for hard algorithmic problems, or after two failed attempts at the same failing test. Do not use it for routine edits, file lookups or questions about this repository.",
+			"Use it to review a proposed design or feature plan before implementation starts when the user asks for a second opinion: paste the plan, the interfaces it touches, the constraints and invariants it must respect, and ask for flaws ranked by severity, concrete alternatives, and tests that are missing. You decide whether to adopt the critique; say what you took and what you rejected and why.",
+			"Write the {{tool}} brief so that a strong engineer who has never seen this repository could solve it: paste the code and error output, do not refer to files by path alone.",
+		]
+	).map((g) => g.replaceAll("{{tool}}", toolName));
+
+	return defineTool({
+		name: toolName,
+		label: `Ask ${label}`,
+		description,
+		promptSnippet: `${toolName}: hand a hard self-contained algorithm or debugging problem (or a plan to review) to ${label} (slow)`,
+		promptGuidelines: guidelines,
+		parameters: Type.Object({
+			brief: Type.String({ description: `Self-contained problem statement with all code, errors and constraints ${label} needs` }),
+		}),
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal, onUpdate) {
+			// re-read config per call so baseUrl/key edits take effect without a restart
+			const cfg = loadFriends().find((x) => x.name === name) ?? f;
+			const bad = checkBrief(cfg, params.brief);
+			if (bad) throw new Error(bad.replace(/^friends:/, `${toolName}:`));
+			const key = readKey(cfg);
+			const ahead = queue.length;
+			if (ahead > 0) onUpdate?.({ content: [{ type: "text", text: `Waiting for ${ahead} earlier ${toolName} call(s)...` }], details: undefined });
+			const r = await queue.run(async () => {
+				if (cfg.tunnel) {
+					const t = await ensureTunnel(cfg.tunnel);
+					if (t !== "up") onUpdate?.({ content: [{ type: "text", text: `SSH tunnel to ${cfg.tunnel.host} ${t}` }], details: undefined });
+				}
+				return askFriend(cfg, key, params.brief, signal, (p) =>
+					onUpdate?.({
+						content: [{ type: "text", text: `${label} thinking: ${Math.round(p.seconds)} s, ${p.reasoningChars} reasoning chars, ${p.answerChars} answer chars` }],
+						details: undefined,
+					}), cfg.system ?? DEFAULT_SYSTEM);
+			});
+			const stats = `[${toolName}: ${Math.round(r.seconds)} s, ${r.promptTokens} prompt tokens (${r.cachedTokens} cached), ${r.completionTokens} completion tokens, finish=${r.finish}]`;
+			if (!r.answer) {
+				throw new Error(
+					r.finish === "length"
+						? `${toolName}: ${label} used the whole ${cfg.maxTokens}-token budget reasoning and gave no answer. ${stats} Narrow the problem or split it, then retry.`
+						: `${toolName}: ${label} returned no answer. ${stats}`,
+				);
+			}
+			const cut = r.finish === "length" ? "\n\nNote: the answer was cut off at the token budget; it may be incomplete." : "";
+			return {
+				content: [{ type: "text", text: `${r.answer}${cut}\n\n${stats}` }],
+				details: { friend: name, seconds: r.seconds, finish: r.finish, reasoningChars: r.reasoningChars },
+				usage: {
+					input: r.promptTokens,
+					output: r.completionTokens,
+					cacheRead: r.cachedTokens,
+					cacheWrite: 0,
+					totalTokens: r.promptTokens + r.completionTokens,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+				},
+			};
+		},
+	});
+}
+
+export default function (pi: ExtensionAPI) {
+	for (const f of loadFriends()) pi.registerTool(makeTool(f));
+
+	// /friends — who is configured, and which tools are live. Status only: the key FILE's
+	// presence is reported, its contents never are (same rule as meta-guard's FORBIDDEN list).
+	pi.registerCommand("friends", {
+		description: "List configured friends (escalation models): tool, endpoint, model, key status",
+		handler: async (_args, ctx) => {
+			const cur = loadFriends(); // fresh read: config edits show up without a restart
+			const lines = [`${cur.length} friend(s) configured — every one is an active tool (no single "current" friend):`];
+			for (const f of cur) {
+				const kf = f.keyFile?.startsWith("~/") ? join(homedir(), f.keyFile.slice(2)) : f.keyFile ?? "";
+				const key = kf && existsSync(kf) ? (readFileSync(kf, "utf8").trim() ? "key ok" : "key EMPTY") : "key MISSING";
+				const bits = [
+					`tool ask_${f.name}`,
+					f.baseUrl,
+					`model=${f.model}`,
+					key,
+					f.tunnel ? `tunnel via ${f.tunnel.host}` : "direct",
+					f.system ? "custom persona" : "default persona",
+				];
+				lines.push(`  ${f.name}: ${bits.join(" | ")}`);
+			}
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/extensions/friends/tunnel.ts

@@ -0,0 +1,92 @@
+// On-demand SSH tunnel for a friend behind SSH (e.g. a laptop that is not always on the LAN). This machine has no service manager (a container with sshd as PID 1), so
+// instead of a service the tool checks the tunnel before every call: it starts ssh if nothing listens on the local port, and
+// restarts it if the host in the config changed since it was started. State (pid + the settings it was started with) lives in
+// ~/.config/pi-friends/tunnel.json. No pi imports (tested by test/tunnel.test.ts).
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { connect } from "node:net";
+
+export interface TunnelConfig {
+	host: string; // ssh target of the Mac, e.g. user@<mac-ip>: change this to point at another address
+	identity?: string; // ssh identity file
+	localPort: number; // loopback port on this machine (must match baseUrl)
+	remotePort: number; // rec's port on the Mac's loopback
+	sshCommand?: string; // default "ssh" (tests use a fake)
+}
+
+export const STATE_PATH = join(homedir(), ".config", "pi-escalation", "tunnel.json");
+const expand = (p: string) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+
+export function portOpen(port: number, ms = 1000): Promise<boolean> {
+	return new Promise((resolve) => {
+		const s = connect({ host: "127.0.0.1", port });
+		const done = (ok: boolean) => {
+			s.destroy();
+			resolve(ok);
+		};
+		s.setTimeout(ms, () => done(false));
+		s.once("connect", () => done(true));
+		s.once("error", () => done(false));
+	});
+}
+
+const alive = (pid: number) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+const sameSettings = (a: TunnelConfig, b: TunnelConfig) =>
+	a.host === b.host && a.identity === b.identity && a.localPort === b.localPort && a.remotePort === b.remotePort;
+
+function readState(path: string): { pid: number; cfg: TunnelConfig } | undefined {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+/** Make sure 127.0.0.1:localPort forwards to the configured Mac. Returns what it did, for the tool's progress line. */
+export async function ensureTunnel(t: TunnelConfig, statePath = STATE_PATH, waitMs = 15000): Promise<"up" | "started" | "restarted"> {
+	const st = readState(statePath);
+	const ours = st && alive(st.pid);
+	const open = await portOpen(t.localPort);
+	if (open && (!ours || sameSettings(st!.cfg, t))) return "up"; // ours with the same settings, or one started by hand
+	if (ours) {
+		// settings changed (e.g. a new host), or our ssh is alive but the forward is dead
+		process.kill(st!.pid, "SIGTERM");
+		for (let i = 0; i < 50 && (await portOpen(t.localPort, 200)); i++) await new Promise((r) => setTimeout(r, 100));
+	}
+	const args = [
+		...(t.identity ? ["-i", expand(t.identity)] : []),
+		"-N", "-o", "BatchMode=yes", "-o", "ExitOnForwardFailure=yes", "-o", "ConnectTimeout=10",
+		"-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=4",
+		"-L", `127.0.0.1:${t.localPort}:127.0.0.1:${t.remotePort}`, t.host,
+	];
+	const child = spawn(t.sshCommand ?? "ssh", args, { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+	let err = "";
+	child.stderr!.on("data", (d) => (err += d));
+	let exited: number | null = null;
+	child.once("exit", (code) => (exited = code ?? -1));
+	const t0 = Date.now();
+	while (Date.now() - t0 < waitMs) {
+		if (await portOpen(t.localPort, 300)) {
+			child.stderr!.destroy();
+			child.unref(); // outlives pi; the next call reuses it
+			writeFileSync(statePath, JSON.stringify({ pid: child.pid, cfg: t }), { mode: 0o600 });
+			return ours ? "restarted" : "started";
+		}
+		if (exited !== null) break;
+		await new Promise((r) => setTimeout(r, 200));
+	}
+	try {
+		child.kill();
+	} catch {}
+	throw new Error(`friends: could not open the SSH tunnel to ${t.host} (${exited !== null ? `ssh exited ${exited}` : "timed out"}): ${err.trim().slice(0, 300)}`);
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "pi-friends",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "pi extension: consult other models on hard problems. Each friend (any OpenAI-compatible endpoint) gets its own ask_<name> tool; briefs are self-contained one-turn exchanges, answers come back without reasoning transcripts.",
+  "keywords": ["pi-package", "pi-extension", "pi", "llm", "coding-agent", "escalation"],
+  "license": "MIT",
+  "author": "Nick Kavassalis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nkavassalis/pi-friends.git"
+  },
+  "homepage": "https://github.com/nkavassalis/pi-friends#readme",
+  "bugs": { "url": "https://github.com/nkavassalis/pi-friends/issues" },
+  "pi": {
+    "extensions": ["./extensions/friends/index.ts"]
+  },
+  "files": ["extensions/friends", "README.md", "LICENSE", "AGENTS.md"],
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts"
+  }
+}