@nimanzik/pi-auto-title 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release as `@nimanzik/pi-auto-title`.
+
+- Name sessions from their first request without blocking the conversation.
+- Preserve skill prefixes and existing or manually edited titles.
+- Support a pinned title model with fallback to the session model.
+- Cancel pending title generation when switching sessions or shutting down.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nimanzik
+
+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,56 @@
-# Temporary Holding Version
+# pi-auto-title
 
-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 extension that names a session from its first request. It sets a temporary
+title immediately, then generates a short title in the background. Skill requests
+keep their `[skill-name]` prefix. Existing or manually edited titles are preserved.
+
+## Installation
+
+Install the published package with:
+
+```sh
+pi install npm:@nimanzik/pi-auto-title
+```
+
+The extension makes an additional model request to generate each new session
+title, which may incur provider costs.
+
+## Model selection
+
+By default, title generation follows the current session model. To use a different
+model without changing the model answering your requests:
+
+```text
+/auto-title model                      # show the effective model
+/auto-title model <provider> <model>   # validate and save a model pin
+/auto-title model reset                # follow the session model again
+```
+
+The pinned model must exist in Pi's model registry and have credentials configured.
+New pins that fail either check are rejected without changing the saved pin.
+
+The pin applies across projects and sessions using the same agent directory.
+It is stored in `<agent-dir>/auto-title.json`, usually
+`~/.pi/agent/auto-title.json`. Pi's `PI_CODING_AGENT_DIR` setting is respected.
+You can also edit the file directly:
+
+```json
+{
+  "provider": "your-provider",
+  "model": "your-model-id"
+}
+```
+
+Configuration is read for each title request and model-status command. Changes
+affect future title requests, not a request already running or an already named
+session. Reset deletes the configuration file.
+
+If the pinned model is unavailable or fails, the extension warns and tries the
+session model once, unless it is the same model. Invalid configuration also warns
+and uses the session model, without overwriting the file. Fallback can send the
+request to a different provider, with that provider's costs and data policies.
+Warnings appear through Pi's notification UI when supported.
+
+Each model attempt has a 15-second timeout, allowing up to 30 seconds with fallback.
+The conversation is not blocked. If generation fails, the temporary title remains.
+Switching sessions or shutting down cancels pending title generation.

package/auto-title.ts

@@ -0,0 +1,183 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const skillPattern = /^\/skill:(\S+)\s*([\s\S]*)/;
+
+const SUMMARY_PROMPT =
+  "Write a short title (5-8 words) for this request. Output only the title, no quotes, no trailing period.";
+
+type ModelPin = { provider: string; model: string };
+
+function readPin(path: string): ModelPin | undefined {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const pin = JSON.parse(text);
+  if (!pin || typeof pin.provider !== "string" || !pin.provider.trim() ||
+      typeof pin.model !== "string" || !pin.model.trim()) {
+    throw new Error(`Invalid model pin in ${path}: expected provider and model strings`);
+  }
+  return { provider: pin.provider.trim(), model: pin.model.trim() };
+}
+
+export default function (pi: ExtensionAPI) {
+  let named = false;
+  let pending: AbortController | undefined;
+  const configPath = join(getAgentDir(), "auto-title.json");
+
+  pi.registerCommand("auto-title", {
+    description: "Show, pin, or reset the title-generation model",
+    handler: async (args, ctx) => {
+      const parts = args.trim().split(/\s+/);
+      try {
+        if (parts.length === 1 && parts[0] === "model") {
+          let pin: ModelPin | undefined;
+          try {
+            pin = readPin(configPath);
+          } catch {
+            ctx.ui.notify(`Auto-title: cannot read ${configPath}; using the session model`, "warning");
+          }
+          const model = pin ? ctx.modelRegistry.find(pin.provider, pin.model) : ctx.model;
+          const available = model && ctx.modelRegistry.hasConfiguredAuth(model);
+          ctx.ui.notify(pin
+            ? `Auto-title pinned: ${pin.provider}/${pin.model}${available ? "" : `; unavailable, session model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}`}`
+            : `Auto-title follows session model: ${model ? `${model.provider}/${model.id}` : "none"}`, "info");
+        } else if (parts.length === 2 && parts[0] === "model" && parts[1] === "reset") {
+          rmSync(configPath, { force: true });
+          ctx.ui.notify("Auto-title now follows the session model", "info");
+        } else if (parts.length === 3 && parts[0] === "model") {
+          const [, provider, id] = parts;
+          const model = ctx.modelRegistry.find(provider, id);
+          if (!model) throw new Error(`Unknown model: ${provider}/${id}`);
+          if (!ctx.modelRegistry.hasConfiguredAuth(model)) throw new Error(`No credentials configured for ${provider}/${id}`);
+          mkdirSync(getAgentDir(), { recursive: true });
+          const temporaryPath = `${configPath}.${randomUUID()}.tmp`;
+          try {
+            writeFileSync(temporaryPath, JSON.stringify({ provider, model: id }, null, 2) + "\n", { flag: "wx" });
+            renameSync(temporaryPath, configPath);
+          } finally {
+            rmSync(temporaryPath, { force: true });
+          }
+          ctx.ui.notify(`Auto-title pinned to ${provider}/${id}`, "info");
+        } else {
+          ctx.ui.notify("Usage: /auto-title model [<provider> <model> | reset]", "info");
+        }
+      } catch (error) {
+        ctx.ui.notify(`Auto-title: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+
+  pi.on("session_start", () => {
+    pending?.abort();
+    pending = undefined;
+    named = !!pi.getSessionName();
+  });
+
+  pi.on("session_shutdown", () => {
+    pending?.abort();
+    pending = undefined;
+  });
+
+  pi.on("input", (event, ctx) => {
+    if (named || pi.getSessionName()) return;
+
+    const match = event.text.match(skillPattern);
+    const prefix = match ? `[${match[1]}] ` : "";
+    const userPrompt = (match ? match[2] : event.text).trim();
+
+    if (!userPrompt && !match) return;
+    named = true;
+
+    if (!userPrompt) {
+      pi.setSessionName(prefix.trim());
+      return;
+    }
+
+    pi.setSessionName(`${prefix}${userPrompt.slice(0, 60)}`);
+    const temporaryName = pi.getSessionName();
+
+    const sessionId = ctx.sessionManager.getSessionId();
+    const task = new AbortController();
+    pending = task;
+
+    // Pi awaits input handlers, so do not return this promise.
+    void (async () => {
+      try {
+        let pin: ModelPin | undefined;
+        try {
+          pin = readPin(configPath);
+        } catch {
+          ctx.ui.notify(`Auto-title: cannot read ${configPath}; using the session model`, "warning");
+        }
+        const sessionModel = ctx.model;
+        const models = pin ? [ctx.modelRegistry.find(pin.provider, pin.model)] : [];
+        if (!pin || sessionModel?.provider !== pin.provider || sessionModel?.id !== pin.model) {
+          models.push(sessionModel);
+        }
+        for (const [index, model] of models.entries()) {
+          if (task.signal.aborted) return;
+          const signal = AbortSignal.any([task.signal, AbortSignal.timeout(15_000)]);
+          let onAbort: (() => void) | undefined;
+          let summary: string;
+          // Generation failures can recover with the session model or the temporary title.
+          try {
+            if (!model) throw new Error("Model unavailable");
+            signal.throwIfAborted();
+            const response = await Promise.race([
+              ctx.modelRegistry.streamSimple(
+                model,
+                {
+                  systemPrompt: SUMMARY_PROMPT,
+                  messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+                },
+                { signal, maxTokens: 64 },
+              ).result(),
+              new Promise<never>((_, reject) => {
+                onAbort = () => reject(signal.reason);
+                signal.addEventListener("abort", onAbort, { once: true });
+                if (signal.aborted) onAbort();
+              }),
+            ]);
+            signal.throwIfAborted();
+            if (response.stopReason !== "stop") throw new Error("Title generation failed");
+            summary = response.content
+              .filter((c): c is { type: "text"; text: string } => c.type === "text")
+              .map((c) => c.text)
+              .join("")
+              .replace(/\s+/g, " ")
+              .trim();
+            if (!summary) throw new Error("Empty title");
+          } catch (error) {
+            if (task.signal.aborted) return;
+            if (pin && index === 0) {
+              ctx.ui.notify(`Auto-title: pinned model ${pin.provider}/${pin.model} failed; ${models.length > 1 && sessionModel ? "trying the session model" : "keeping the temporary title"}`, "warning");
+            } else {
+              throw error;
+            }
+            continue;
+          } finally {
+            if (onAbort) signal.removeEventListener("abort", onAbort);
+          }
+
+          if (pending === task && ctx.sessionManager.getSessionId() === sessionId &&
+              pi.getSessionName() === temporaryName) {
+            pi.setSessionName(`${prefix}${summary}`.slice(0, 80).trim());
+          }
+          return;
+        }
+      } catch (error) {
+        // Detached-task boundary: report failures instead of losing rejected promises.
+        ctx.ui.notify(`Auto-title failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+      } finally {
+        if (pending === task) pending = undefined;
+      }
+    })();
+  });
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@nimanzik/pi-auto-title",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Automatically name Pi sessions from their first request.",
+  "type": "module",
+  "license": "MIT",
+  "readme": "README.md",
+  "author": {
+    "name": "Nima Nooshiri"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimanzik/pi-kit.git",
+    "directory": "extensions/pi-auto-title"
+  },
+  "bugs": {
+    "url": "https://github.com/nimanzik/pi-kit/issues"
+  },
+  "homepage": "https://github.com/nimanzik/pi-kit/tree/main/extensions/pi-auto-title#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["auto-title.ts", "CHANGELOG.md", "README.md", "LICENSE"],
+  "keywords": ["pi-package", "pi-extension"],
+  "pi": {
+    "extensions": ["./auto-title.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules --test auto-title.test.mjs",
+    "typecheck": "tsc"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  }
+}