@d3ara1n/pi-session-namer 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @d3ara1n/pi-session-namer
+
+Auto-name pi sessions using a cheap side agent.
+
+On the first user prompt of a new session, calls a lightweight side agent model
+to generate a concise session title, then sets it via `pi.setSessionName()`.
+Subsequent turns are skipped with near-zero overhead.
+
+## Features
+
+- **Zero-config**: Works out of the box with pi-model-roles' `utility` role
+- **First-turn only**: Adds ~0.5-1s latency on the first prompt, zero overhead after
+- **Graceful fallback**: If the side agent fails, truncates the user prompt as name
+- **Manual rename**: `/namer:rename` to regenerate at any time
+
+## Configuration
+
+In `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "sessionNamer": {
+    "enabled": true,
+    "sideAgentRole": "utility",
+    "maxLength": 50,
+    "language": "zh"
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Global on/off switch |
+| `sideAgentRole` | `"utility"` | pi-model-roles role for the naming side agent |
+| `maxLength` | `50` | Maximum name length in characters |
+
+Project-level `.pi/settings.json` overrides global settings.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/namer` | Show status and config |
+| `/namer on` | Enable auto-naming |
+| `/namer off` | Disable auto-naming |
+| `/namer:rename` | Regenerate session name from last prompt |
+
+## Dependencies
+
+- `@earendil-works/pi-ai` — `complete()` for LLM calls
+- `@earendil-works/pi-coding-agent` — Extension API
+- `@d3ara1n/pi-model-roles` — Model role resolution
+
+## Install
+
+Add to `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "extensions": [
+    "/path/to/pi-extensions/packages/pi-session-namer"
+  ]
+}
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@d3ara1n/pi-session-namer",
+  "version": "0.1.0",
+  "description": "Auto-name pi sessions using a cheap side agent — generates concise titles from the first user message",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@d3ara1n/pi-model-roles": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@d3ara1n/pi-model-roles": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@d3ara1n/pi-model-roles": "^0.1.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d3ara1n/pi-extensions",
+    "directory": "packages/pi-session-namer"
+  },
+  "license": "MIT"
+}

package/src/config.ts

@@ -0,0 +1,64 @@
+/**
+ * Read session-namer configuration from settings files.
+ *
+ * Global (~/.pi/agent/settings.json) + project (.pi/settings.json),
+ * project overrides global.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SessionNamerConfig } from "./types.ts";
+import { DEFAULT_CONFIG } from "./types.ts";
+
+function getAgentDir(): string {
+	const envDir = process.env.PI_AGENT_DIR;
+	if (envDir) return envDir;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+function readSettingsFile(filePath: string): any {
+	try {
+		if (!fs.existsSync(filePath)) return {};
+		const content = fs.readFileSync(filePath, "utf-8");
+		const stripped = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+		return JSON.parse(stripped);
+	} catch {
+		return {};
+	}
+}
+
+function merge(target: any, source: any): any {
+	if (!source || typeof source !== "object") return target;
+	if (!target || typeof target !== "object") return source;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+			result[key] = merge(result[key], source[key]);
+		} else {
+			result[key] = source[key];
+		}
+	}
+	return result;
+}
+
+/**
+ * Load session-namer config from merged settings.
+ * @param cwd - Project working directory
+ */
+export function loadNamerConfig(cwd?: string): SessionNamerConfig {
+	const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
+	const projectSettings = cwd
+		? readSettingsFile(path.join(cwd, ".pi", "settings.json"))
+		: {};
+	const settings = merge(globalSettings, projectSettings);
+
+	const raw = settings?.sessionNamer;
+	if (!raw) return DEFAULT_CONFIG;
+
+	return {
+		enabled: raw.enabled ?? DEFAULT_CONFIG.enabled,
+		sideAgentRole: raw.sideAgentRole ?? DEFAULT_CONFIG.sideAgentRole,
+		maxLength: raw.maxLength ?? DEFAULT_CONFIG.maxLength,
+	};
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * pi-session-namer — Auto-name pi sessions using a cheap side agent.
+ *
+ * On the first user prompt of a new session, calls a lightweight side agent
+ * to generate a concise session title, then sets it via pi.setSessionName().
+ * Subsequent turns are skipped with near-zero overhead.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
+import { DEFAULT_CONFIG } from "./types.ts";
+import type { SessionNamerConfig } from "./types.ts";
+import { loadNamerConfig } from "./config.ts";
+import { generateSessionName } from "./namer.ts";
+
+export default function sessionNamerExtension(pi: ExtensionAPI) {
+	let config: SessionNamerConfig = DEFAULT_CONFIG;
+	let hasNamed = false;
+	let lastPrompt = "";
+
+	// ── session_start: load config, reset flag ──────────────────────
+	pi.on("session_start", async (_event, _ctx) => {
+		config = loadNamerConfig(_ctx.cwd);
+		hasNamed = false;
+		lastPrompt = "";
+
+		// 如果会话已有名称（resume/fork/用户手动命名），不再自动命名
+		const existingName = pi.getSessionName();
+		if (existingName) {
+			hasNamed = true;
+		}
+	});
+
+	// ── before_agent_start: auto-name on first prompt ───────────────
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!config.enabled || hasNamed) return;
+
+		// Cache prompt for /namer:rename
+		lastPrompt = event.prompt;
+
+		// Skip empty prompts (e.g. image-only messages)
+		if (!event.prompt?.trim()) return;
+
+		// 标记为已处理（无论后续成功与否，不重试）
+		hasNamed = true;
+
+		let rolesApi;
+		try {
+			rolesApi = getModelRolesAPI();
+		} catch {
+			console.warn("[pi-session-namer] pi-model-roles not initialized — skipping");
+			return;
+		}
+
+		const resolved = await rolesApi.resolveRoleAsync(config.sideAgentRole);
+		if (!resolved.model) {
+			console.warn(`[pi-session-namer] Side agent role "${config.sideAgentRole}" not available — skipping`);
+			return;
+		}
+
+		const name = await generateSessionName(
+			resolved.model,
+			resolved.apiKey,
+			resolved.headers,
+			config,
+			event.prompt,
+		);
+
+		pi.setSessionName(name);
+		console.log(`[pi-session-namer] Session named: ${name}`);
+	});
+
+	// ── /namer — show status ────────────────────────────────────────
+	pi.registerCommand("namer", {
+		description: "Show session namer status and config",
+		handler: async (args, ctx) => {
+			const value = (args ?? "").trim().toLowerCase();
+
+			// Handle on/off toggles
+			if (value === "on") {
+				config.enabled = true;
+				ctx.ui.notify("Session Namer: enabled", "info");
+				return;
+			}
+			if (value === "off") {
+				config.enabled = false;
+				ctx.ui.notify("Session Namer: disabled", "info");
+				return;
+			}
+
+			const currentName = pi.getSessionName();
+			const lines = [
+				`Session Namer: ${config.enabled ? "enabled" : "disabled"}`,
+				`Side agent role: ${config.sideAgentRole}`,
+				`Max length: ${config.maxLength}`,
+				`Current name: ${currentName ?? "(none)"}`,
+				`Has auto-named: ${hasNamed}`,
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ── /namer:rename — force regenerate ────────────────────────────
+	pi.registerCommand("namer:rename", {
+		description: "Regenerate session name from the last user prompt",
+		handler: async (_args, ctx) => {
+			if (!lastPrompt?.trim()) {
+				ctx.ui.notify("No user prompt available to generate a name from.", "warning");
+				return;
+			}
+
+			let rolesApi;
+			try {
+				rolesApi = getModelRolesAPI();
+			} catch {
+				ctx.ui.notify("pi-model-roles not initialized. Cannot rename.", "error");
+				return;
+			}
+
+			const resolved = await rolesApi.resolveRoleAsync(config.sideAgentRole);
+			if (!resolved.model) {
+				ctx.ui.notify(
+					`Side agent role "${config.sideAgentRole}" not available. Cannot rename.`,
+					"error",
+				);
+				return;
+			}
+
+			const name = await generateSessionName(
+				resolved.model,
+				resolved.apiKey,
+				resolved.headers,
+				config,
+				lastPrompt,
+			);
+
+			pi.setSessionName(name);
+			ctx.ui.notify(`Session renamed: ${name}`, "info");
+		},
+	});
+}

package/src/namer.ts

@@ -0,0 +1,96 @@
+/**
+ * Side agent invocation for session naming.
+ *
+ * Calls the side agent model using pi-ai's complete() function
+ * and returns a cleaned session name string.
+ */
+
+import { complete } from "@earendil-works/pi-ai";
+import type { SessionNamerConfig } from "./types.ts";
+
+/**
+ * Build the system prompt for the naming side agent.
+ */
+export function buildNamerSystemPrompt(maxLength: number): string {
+	return [
+		`You are a session naming assistant. Generate a concise title for a coding session based on the user's first message.`,
+		``,
+		`Rules:`,
+		`- Output in the SAME language as the user's message`,
+		`- Maximum ${maxLength} characters`,
+		`- Output ONLY the title, no quotes, no prefix, no explanation`,
+		`- Summarize intent, do not copy the original message verbatim`,
+		`- If the message mentions specific files, modules, or functions, keep those names`,
+		`- Be specific: "Fix auth token refresh bug" is better than "Fix a bug"`,
+	].join("\n");
+}
+
+/**
+ * Call the side agent to generate a session name.
+ */
+export async function generateSessionName(
+	sideModel: any,
+	apiKey: string | undefined,
+	headers: Record<string, string> | undefined,
+	config: SessionNamerConfig,
+	userPrompt: string,
+): Promise<string> {
+	const systemPrompt = buildNamerSystemPrompt(config.maxLength);
+
+	// Truncate very long prompts to avoid wasting tokens
+	const truncatedPrompt = userPrompt.length > 2000
+		? userPrompt.slice(0, 2000) + "..."
+		: userPrompt;
+
+	const options: Record<string, any> = {
+		maxTokens: 64,
+	};
+
+	if (apiKey) options.apiKey = apiKey;
+	if (headers) options.headers = headers;
+
+	try {
+		const result = await complete(sideModel, {
+			systemPrompt,
+			messages: [{ role: "user", content: truncatedPrompt }],
+		}, options);
+
+		const raw = result.content
+			?.filter((block: any) => block.type === "text")
+			?.map((block: any) => block.text)
+			?.join("")
+			?.trim() ?? "";
+
+		return cleanSessionName(raw, config.maxLength);
+	} catch (err) {
+		console.warn("[pi-session-namer] Side agent call failed:", err);
+		// Fallback: truncate user prompt as name
+		return userPrompt.slice(0, config.maxLength).replace(/\n/g, " ").trim();
+	}
+}
+
+/**
+ * Clean and truncate the generated name.
+ */
+function cleanSessionName(raw: string, maxLength: number): string {
+	let name = raw.trim();
+
+	// Strip surrounding quotes if present
+	if (
+		(name.startsWith('"') && name.endsWith('"')) ||
+		(name.startsWith("'") && name.endsWith("'")) ||
+		(name.startsWith("「") && name.endsWith("」"))
+	) {
+		name = name.slice(1, -1);
+	}
+
+	// Remove newlines
+	name = name.replace(/\n/g, " ").trim();
+
+	// Truncate
+	if (name.length > maxLength) {
+		name = name.slice(0, maxLength - 3) + "...";
+	}
+
+	return name || "New session";
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared types for pi-session-namer.
+ */
+
+/** Configuration for the session-namer extension, stored in settings.json. */
+export interface SessionNamerConfig {
+  /** Whether auto-naming is enabled */
+  enabled: boolean;
+  /** pi-model-roles role name for the side agent */
+  sideAgentRole: string;
+  /** Maximum name length (characters) */
+  maxLength: number;
+}
+
+export const DEFAULT_CONFIG: SessionNamerConfig = {
+  enabled: true,
+  sideAgentRole: "utility",
+  maxLength: 50,
+};