@fyeeme/pi-session-name 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2025-07-15
+
+### Fixed
+
+- Race condition where auto-generated title could overwrite manual rename when `generateTitle` async call completes after user renamed the session
+
+### Added
+
+- `/rename [name]` command: manually rename the current session on demand. With
+  a name argument it sets that name; with no argument it auto-generates one from
+  the conversation. Invoking it locks out background auto-naming (manual
+  control), consistent with `/name`.
+
+### Changed
+
+- Title-generation prompt now favors descriptive titles (key entity + action +
+  goal, ~15-40 characters) over terse labels. Previously the prompt emphasized
+  "short/concise", which produced overly brief session names.
+
+## [1.0.0] - 2026-07-20
+
+### Added
+
+- Initial release
+- Auto-name pi sessions with a short LLM-generated title on first `agent_settled`
+- `first` mode (default): name once, never overwrite
+- `auto` mode: re-evaluate each turn, rename when the topic drifts (LLM returns `KEEP` or a new title)
+- Never overwrites manual names (`/name`, `--name`, RPC, other extensions)
+- Title follows the language of the user's first message
+- Config via `.pi/session-name.json` and `PI_SESSION_NAME_*` env vars

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fyeeme
+
+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,72 @@
+# pi-session-name
+
+Auto-name your [pi](https://pi.dev) sessions with a short, LLM-generated title so
+`pi --resume` lists are easy to scan — instead of the raw first message.
+
+## Install
+
+```bash
+# Global (user) install
+pi install npm:@fyeeme/pi-session-name
+
+# Project-local (.pi/settings.json)
+pi install -l npm:@fyeeme/pi-session-name
+
+# Try once without saving
+pi -e npm:@fyeeme/pi-session-name
+```
+
+Requires pi `>= 0.80.0` (uses the `agent_settled` / `session_info_changed` events).
+
+## Behavior
+
+- When the first agent run of a session **settles**, the extension asks the model
+  for a descriptive title (same language as your first message) — key entity +
+  action + goal, not a terse label — and writes it via `setSessionName`. It then
+  shows up in the resume picker immediately.
+- **Never overwrites a name you set manually** (`/name`, `--name`, the picker's
+  rename, or any other extension). Once it detects an external rename it locks
+  itself for the rest of the session.
+- Two modes (config `mode`):
+  - `first` (default) — name once, then leave it alone.
+  - `auto` — re-evaluate each turn; the model replies `KEEP` or a new title, so
+    the name tracks the current topic.
+- **`/rename [name]`** — manually rename the current session on demand. With a
+  name argument it sets that name; with no argument it generates one from the
+  conversation (same descriptive prompt as auto-naming). Invoking `/rename` is a
+  manual action, so it locks out background auto-naming for the rest of the
+  session — you've taken control.
+
+## Configuration
+
+Create `.pi/session-name.json` in your project root:
+
+```json
+{ "mode": "auto", "maxLength": 200, "model": { "provider": "openai", "id": "gpt-4o-mini" } }
+```
+
+| Option | Default | Env override | Notes |
+|---|---|---|---|
+| `mode` | `"first"` | `PI_SESSION_NAME_MODE` | `first` \| `auto` |
+| `maxLength` | `200` | `PI_SESSION_NAME_MAX_LENGTH` | Title character cap |
+| `enabled` | `true` | `PI_SESSION_NAME_ENABLED=false` | Master switch |
+| `model` | current session model | `PI_SESSION_NAME_MODEL_PROVIDER` + `PI_SESSION_NAME_MODEL_ID` | Override the model used to generate titles |
+
+By default the extension uses the model you're already chatting with (`ctx.model`),
+so no extra API key is needed.
+
+## Failure handling
+
+If the model is unavailable, has no API key, or returns garbage, the extension
+stays silent — your session is never blocked. It retries on the next turn while
+the session is still unnamed.
+
+## Manual smoke test
+
+1. `pi -e ./packages/extensions/pi-session-name/index.ts`, ask a question in a
+   fresh session, wait for the reply → the resume picker shows a generated title.
+2. `/name foo`, chat a few turns → name stays `foo` (locked).
+3. `mode: "auto"`: shift topic across turns → name updates; same topic → stays.
+4. `/rename foo` → name becomes `foo` and stays (locked). `/rename` with no
+   argument → generates a fresh name from the conversation.
+5. Unset the model's API key → no errors, session runs normally.

package/index.ts

@@ -0,0 +1,292 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { complete } from "@earendil-works/pi-ai/compat";
+
+// ---------------------------------------------------------------------------
+// Types & helpers for buildConversationText
+// ---------------------------------------------------------------------------
+
+type ContentBlock = { type?: string; text?: string };
+export type SessionEntry = { type: string; message?: { role?: string; content?: unknown } };
+
+const extractText = (content: unknown): string[] => {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	const parts: string[] = [];
+	for (const part of content) {
+		if (part && typeof part === "object") {
+			const b = part as ContentBlock;
+			if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+		}
+	}
+	return parts;
+};
+
+const truncate = (s: string, max: number): string => (s.length <= max ? s : `${s.slice(0, max)}\u2026`);
+
+export function buildConversationText(
+	entries: SessionEntry[],
+	opts: { maxMessages?: number; maxCharsPerMessage?: number } = {},
+): string {
+	const maxMessages = opts.maxMessages ?? 8;
+	const maxCharsPerMessage = opts.maxCharsPerMessage ?? 600;
+	const msgs = entries
+		.filter((e) => e.type === "message" && (e.message?.role === "user" || e.message?.role === "assistant"))
+		.map((e) => ({
+			role: e.message!.role as "user" | "assistant",
+			text: extractText(e.message!.content).join("\n").trim(),
+		}))
+		.filter((m) => m.text.length > 0);
+	if (msgs.length === 0) return "";
+	const selected = msgs.length > maxMessages ? [msgs[0], ...msgs.slice(-(maxMessages - 1))] : msgs;
+	return selected
+		.map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${truncate(m.text, maxCharsPerMessage)}`)
+		.join("\n\n");
+}
+
+// ---------------------------------------------------------------------------
+// cleanTitle — strip wrapping quotes/brackets, collapse whitespace, truncate
+// ---------------------------------------------------------------------------
+
+export function cleanTitle(raw: string, maxLength: number = 200): string | null {
+	if (!raw) return null;
+	let t = raw.trim();
+	t = t.replace(/^["'`\u300C\u300E\uFF08(\[]+|["'`\u300D\u300F\uFF09)\].]+$/g, "").trim();
+	t = t.replace(/\s+/g, " ");
+	t = t.replace(/[.\u3002!\uFF01?\uFF1F]+$/g, "");
+	if (!t) return null;
+	if (t.length > maxLength) t = t.slice(0, maxLength).trim();
+	return t.length > 0 ? t : null;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builders — first-title & auto-rename prompts
+// ---------------------------------------------------------------------------
+
+export function buildFirstPrompt(
+	conversationText: string,
+	opts: { maxLength?: number } = {},
+): string {
+	const maxLength = opts.maxLength ?? 200;
+	return [
+		"You generate a descriptive title for this conversation so the user can find it later in a session list.",
+		"Rules:",
+		'- Output ONLY the title text. No quotes, no trailing punctuation, no explanation.',
+		"- Use the SAME language as the user's first message.",
+		'- Be descriptive, not terse: include the key entity (class, component, or concept), the action, and the goal — not a vague category.',
+		`- Aim for roughly 15-40 characters; never exceed ${maxLength} characters.`,
+		"",
+		"<conversation>",
+		conversationText,
+		"</conversation>",
+	].join("\n");
+}
+
+export function buildAutoPrompt(
+	currentName: string,
+	conversationText: string,
+	opts: { maxLength?: number } = {},
+): string {
+	const maxLength = opts.maxLength ?? 200;
+	return [
+		"You decide whether the session title still matches the conversation.",
+		`- Current title: ${currentName}`,
+		"If the title is still accurate, reply with exactly: KEEP",
+		"If it is inaccurate or too vague now, output a NEW descriptive title.",
+		"Rules for a new title:",
+		'- ONLY the title text. No quotes, no trailing punctuation, no explanation.',
+		"- Use the SAME language as the user's first message.",
+		'- Be descriptive, not terse: include the key entity (class, component, or concept), the action, and the goal — not a vague category.',
+		`- Aim for roughly 15-40 characters; never exceed ${maxLength} characters.`,
+		"",
+		"<conversation>",
+		conversationText,
+		"</conversation>",
+	].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// SessionNameConfig + loadConfig
+// ---------------------------------------------------------------------------
+
+export interface SessionNameConfig {
+	mode: "first" | "auto";
+	enabled: boolean;
+	maxLength: number;
+	model?: { provider: string; id: string };
+}
+
+const DEFAULT_CONFIG: SessionNameConfig = { mode: "first", enabled: true, maxLength: 200 };
+
+export function loadConfig(cwd: string, env: Record<string, string | undefined> = process.env): SessionNameConfig {
+	let fileCfg: Partial<SessionNameConfig> = {};
+	const file = join(cwd, ".pi", "session-name.json");
+	try {
+		fileCfg = JSON.parse(readFileSync(file, "utf8")) as Partial<SessionNameConfig>;
+	} catch {
+		// missing or malformed config — ignore, fall back to defaults
+	}
+	const cfg: SessionNameConfig = { ...DEFAULT_CONFIG, ...fileCfg };
+	if (env.PI_SESSION_NAME_MODE === "first" || env.PI_SESSION_NAME_MODE === "auto") cfg.mode = env.PI_SESSION_NAME_MODE;
+	if (env.PI_SESSION_NAME_ENABLED === "false") cfg.enabled = false;
+	if (env.PI_SESSION_NAME_MAX_LENGTH) {
+		const n = Number(env.PI_SESSION_NAME_MAX_LENGTH);
+		if (Number.isFinite(n) && n > 0) cfg.maxLength = n;
+	}
+	const provider = env.PI_SESSION_NAME_MODEL_PROVIDER;
+	const id = env.PI_SESSION_NAME_MODEL_ID;
+	if (provider && id) cfg.model = { provider, id };
+	return cfg;
+}
+
+// ---------------------------------------------------------------------------
+// ModelAuth + resolveModelAndAuth
+// ---------------------------------------------------------------------------
+
+export type ModelAuth = { model: Model<any>; apiKey: string; headers: Record<string, string> | undefined };
+
+export async function resolveModelAndAuth(
+	ctx: ExtensionContext,
+	cfg: SessionNameConfig,
+	getModelFn?: (provider: string, id: string) => Model<any> | undefined,
+): Promise<ModelAuth | null> {
+	const find = getModelFn ?? ((p: string, i: string) => ctx.modelRegistry.find(p, i) as Model<any> | undefined);
+	const model = cfg.model ? find(cfg.model.provider, cfg.model.id) : ctx.model;
+	if (!model) return null;
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth?.ok || !auth.apiKey) return null;
+	return { model, apiKey: auth.apiKey, headers: auth.headers };
+}
+
+// ---------------------------------------------------------------------------
+// generateTitle — call LLM to produce a short title
+// ---------------------------------------------------------------------------
+
+export async function generateTitle(
+	prompt: string,
+	auth: ModelAuth,
+	completeFn: typeof complete = complete,
+): Promise<string> {
+	const response = await completeFn(
+		auth.model,
+		{
+			messages: [
+				{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() },
+			],
+		},
+		{ apiKey: auth.apiKey, headers: auth.headers },
+	);
+	return response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n")
+		.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Pi extension entry point
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI): void {
+	let manuallyLocked = false;
+	let inFlight = false;
+	let lastAutoName: string | undefined;
+	let cfg: SessionNameConfig | null = null;
+
+	pi.on("session_start", () => {
+		inFlight = false;
+		lastAutoName = undefined;
+		cfg = null;
+		manuallyLocked = !!pi.getSessionName();
+	});
+
+	pi.on("session_info_changed", (event) => {
+		if (event.name === lastAutoName) return;
+		manuallyLocked = true;
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (cfg === null) cfg = loadConfig(ctx.cwd);
+		if (!cfg.enabled || manuallyLocked || inFlight) return;
+
+		const currentName = pi.getSessionName();
+		if (cfg.mode === "first" && (lastAutoName !== undefined || currentName)) return;
+
+		inFlight = true;
+		try {
+			const auth = await resolveModelAndAuth(ctx, cfg);
+			if (!auth) return;
+
+			const text = buildConversationText(ctx.sessionManager.getBranch());
+			if (!text.trim()) return;
+
+			let title: string | null;
+			if (cfg.mode === "first" || !currentName) {
+				title = cleanTitle(await generateTitle(buildFirstPrompt(text, cfg), auth), cfg.maxLength);
+			} else {
+				const verdict = await generateTitle(buildAutoPrompt(currentName, text, cfg), auth);
+				title = /^keep$/i.test(verdict.trim()) ? null : cleanTitle(verdict, cfg.maxLength);
+			}
+			if (!title) return;
+
+			// Re-check after async gap: manual rename or external setSessionName
+			// may have fired while generateTitle was in flight.
+			if (manuallyLocked || pi.getSessionName() !== currentName) return;
+
+			lastAutoName = title;
+			pi.setSessionName(title);
+		} catch {
+			// silent: failure does not block the session; first mode retries next round, auto mode skips this round
+		} finally {
+			inFlight = false;
+		}
+	});
+
+	pi.registerCommand("rename", {
+		description: "Rename this session. Pass a name, or leave empty to auto-generate one from the conversation.",
+		handler: async (args, ctx) => {
+			// /rename is a manual action: take control and stop background auto-naming
+			manuallyLocked = true;
+			const cfg = loadConfig(ctx.cwd);
+			const name = args.trim();
+
+			if (name) {
+				const cleaned = cleanTitle(name, cfg.maxLength);
+				if (!cleaned) {
+					ctx.ui.notify("Invalid name", "warning");
+					return;
+				}
+				lastAutoName = cleaned;
+				pi.setSessionName(cleaned);
+				ctx.ui.notify(`Renamed to: ${cleaned}`, "info");
+				return;
+			}
+
+			// no argument → generate a name from the conversation
+			const auth = await resolveModelAndAuth(ctx, cfg);
+			if (!auth) {
+				ctx.ui.notify("Cannot generate a name: model unavailable or no API key", "warning");
+				return;
+			}
+			const text = buildConversationText(ctx.sessionManager.getBranch());
+			if (!text.trim()) {
+				ctx.ui.notify("No conversation to generate a name from yet", "warning");
+				return;
+			}
+			try {
+				const title = cleanTitle(await generateTitle(buildFirstPrompt(text, cfg), auth), cfg.maxLength);
+				if (!title) {
+					ctx.ui.notify("Could not generate a name from the model response", "warning");
+					return;
+				}
+				lastAutoName = title;
+				pi.setSessionName(title);
+				ctx.ui.notify(`Renamed to: ${title}`, "info");
+			} catch {
+				ctx.ui.notify("Failed to generate a name", "error");
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@fyeeme/pi-session-name",
+	"version": "1.0.1",
+	"description": "Auto-name pi sessions with a short LLM-generated title so --resume lists are easy to scan. Supports first (once) and auto (content-aware rename) modes; never overwrites manual names.",
+	"type": "module",
+	"license": "MIT",
+	"author": "fyeeme",
+	"publishConfig": { "access": "public" },
+	"repository": { "type": "git", "url": "https://github.com/fyeeme/pi-packages" },
+	"bugs": { "url": "https://github.com/fyeeme/pi-packages/issues" },
+	"homepage": "https://github.com/fyeeme/pi-packages#readme",
+	"engines": { "node": ">=18" },
+	"keywords": ["pi-package", "pi", "session", "auto-name", "rename", "resume"],
+	"files": ["index.ts", "README.md", "LICENSE", "CHANGELOG.md"],
+	"pi": { "extensions": ["./index.ts"] },
+	"scripts": { "test": "vitest --run", "typecheck": "tsc" },
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.80.0",
+		"@earendil-works/pi-ai": ">=0.80.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@earendil-works/pi-ai": "0.80.10",
+		"@types/node": "22.19.19",
+		"typescript": "5.9.3",
+		"vitest": "3.2.7"
+	}
+}