@sassywares/pi-extensions 0.0.0-stage → 0.3.1

package/extensions/auto-title.ts

@@ -0,0 +1,178 @@
+/**
+ * Auto-title
+ *
+ * Generates a short session title after the first meaningful turn, and adds
+ * `/title` to regenerate or set one manually. Titles use pi's native session
+ * name, so they appear in the session picker, footer, and terminal title.
+ *
+ * Disable auto-generation with PI_AUTO_TITLE=0.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const MAX_TITLE_LENGTH = 60;
+const AUTO_TITLE_DISABLED = process.env.PI_AUTO_TITLE === "0";
+
+let generationToken = 0;
+let generating = false;
+let autoAttemptedSessionId: string | undefined;
+
+function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (part): part is { type: "text"; text: string } =>
+        !!part &&
+        typeof part === "object" &&
+        (part as { type?: unknown }).type === "text" &&
+        typeof (part as { text?: unknown }).text === "string",
+    )
+    .map((part) => part.text)
+    .join("\n");
+}
+
+function normalizeTitle(raw: string): string {
+  let title = (raw.split(/\r?\n/, 1)[0] ?? "").trim();
+  title = title.replace(/^#+\s*/, "");
+  title = title.replace(/^(?:session\s+)?title\s*:\s*/i, "");
+  title = title.replace(/^[`"'“”‘’]+|[`"'“”‘’]+$/g, "").trim();
+  title = title.replace(/[.!?;:,，。！？；：]+$/, "").trim();
+  if (title.length > MAX_TITLE_LENGTH) {
+    title = title.slice(0, MAX_TITLE_LENGTH).replace(/\s+\S*$/, "").trim();
+  }
+  return title;
+}
+
+function hasAssistantText(ctx: ExtensionContext): boolean {
+  return ctx.sessionManager.getBranch().some(
+    (entry) =>
+      entry.type === "message" &&
+      entry.message.role === "assistant" &&
+      textOf(entry.message.content).trim().length > 0,
+  );
+}
+
+function buildTranscript(ctx: ExtensionContext): string {
+  const parts: string[] = [];
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (message.role !== "user" && message.role !== "assistant") continue;
+
+    const text = textOf(message.content).trim();
+    if (!text) continue;
+
+    // Titles only need the gist of the opening turns.
+    parts.push(`${message.role.toUpperCase()}: ${text.slice(0, 3000)}`);
+    if (parts.length >= 4) break;
+  }
+  return parts.join("\n\n").slice(0, 8000);
+}
+
+async function generateTitle(ctx: ExtensionContext): Promise<string | undefined> {
+  if (!ctx.model) return undefined;
+  const transcript = buildTranscript(ctx);
+  if (!transcript) return undefined;
+
+  const abort = new AbortController();
+  const timeout = setTimeout(() => abort.abort(), 15_000);
+  try {
+    const result = await ctx.modelRegistry.complete(
+      ctx.model,
+      {
+        systemPrompt:
+          "You create concise session titles for a coding agent. Reply with only the title: " +
+          "2-6 words, no quotes, no markdown, no trailing punctuation. " +
+          "Describe the concrete task, not the conversation. Use the user's language.",
+        messages: [
+          {
+            role: "user",
+            content: `Create a title for this session:\n\n${transcript}`,
+            timestamp: Date.now(),
+          },
+        ],
+      },
+      { maxTokens: 32, temperature: 0.2, signal: abort.signal },
+    );
+
+    if (result.stopReason === "error" || result.stopReason === "aborted") return undefined;
+    return normalizeTitle(textOf(result.content));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function titleCurrentSession(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  force: boolean,
+): Promise<string | undefined> {
+  if (generating) return undefined;
+
+  const sessionId = ctx.sessionManager.getSessionId();
+  const token = generationToken;
+  const existing = pi.getSessionName();
+  if (!force && existing?.trim()) return existing;
+
+  generating = true;
+  try {
+    const title = await generateTitle(ctx);
+    if (!title) return undefined;
+
+    // The user may have switched sessions or named this one while we waited.
+    if (token !== generationToken || ctx.sessionManager.getSessionId() !== sessionId) return undefined;
+    if (!force && pi.getSessionName()?.trim()) return pi.getSessionName();
+
+    pi.setSessionName(title);
+    return title;
+  } finally {
+    generating = false;
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", () => {
+    generationToken++;
+    generating = false;
+    autoAttemptedSessionId = undefined;
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    if (AUTO_TITLE_DISABLED) return;
+    if (pi.getSessionName()?.trim()) return;
+
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (autoAttemptedSessionId === sessionId) return;
+    if (!hasAssistantText(ctx)) return;
+
+    // Try once per session. `/title` can retry after a provider failure.
+    autoAttemptedSessionId = sessionId;
+
+    // Do not delay the turn; the title can arrive a moment later.
+    void titleCurrentSession(pi, ctx, false).catch(() => {
+      // A title is a convenience; never surface provider errors into the session.
+    });
+  });
+
+  pi.registerCommand("title", {
+    description: "Generate a title from the conversation, or set one: /title <text>",
+    handler: async (args, ctx) => {
+      const requested = args.trim();
+      if (requested) {
+        const title = normalizeTitle(requested) || requested;
+        pi.setSessionName(title);
+        ctx.ui.notify(`Session titled: ${title}`, "info");
+        return;
+      }
+
+      ctx.ui.notify("Generating session title…", "info");
+      const title = await titleCurrentSession(pi, ctx, true);
+      if (title) {
+        ctx.ui.notify(`Session titled: ${title}`, "info");
+      } else {
+        ctx.ui.notify("Could not generate a title from this conversation.", "warning");
+      }
+    },
+  });
+}

package/extensions/handoff.ts

@@ -0,0 +1,189 @@
+/**
+ * Sassy Handoff - summarize the current session and continue in a fresh one.
+ *
+ * Usage:
+ *   /handoff <goal for the next session>
+ *   /handoff mode:auto <goal for the next session>
+ *
+ * Default: generate a focused continuation prompt, let the user edit it, then
+ * open a new session with the prompt seeded in the editor (submit to continue).
+ *
+ * mode:auto: generate the prompt and start the new session immediately, sending
+ * the prompt as its first user message (skill commands inside it are expanded).
+ *
+ * Session replacement is only available from command handlers, which is why
+ * this is a command and not a tool.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { type Message, uuidv7 } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
+
+1. Summarizes the relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists the relevant files that were discussed or modified, with the specific part that matters
+3. States the next task clearly, based on the user's goal
+4. Is self-contained - the new thread must be able to proceed without the old conversation
+
+If the user's goal names a plan file and a phase, make the plan path and phase explicit, and end with the exact follow-up command to run them (for example: run /skill:sassy-work <plan> phase:<n>).
+
+Format your response as the prompt itself. No preamble. Example shape:
+
+## Context
+We were building X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file.ts - what matters there
+
+## Task
+[Clear description of what to do next, including the exact command to run]`;
+
+function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "message") {
+		return entry.message;
+	}
+	if (entry.type === "compaction") {
+		return {
+			role: "compactionSummary",
+			summary: entry.summary,
+			tokensBefore: entry.tokensBefore,
+			timestamp: new Date(entry.timestamp).getTime(),
+		};
+	}
+	return undefined;
+}
+
+function getHandoffMessages(branch: SessionEntry[]): AgentMessage[] {
+	let compactionIndex = -1;
+	for (let i = branch.length - 1; i >= 0; i--) {
+		if (branch[i].type === "compaction") {
+			compactionIndex = i;
+			break;
+		}
+	}
+	if (compactionIndex < 0) {
+		return branch.map(entryToMessage).filter((message) => message !== undefined);
+	}
+
+	const compaction = branch[compactionIndex];
+	const firstKeptIndex =
+		compaction.type === "compaction" ? branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId) : -1;
+	const compactedBranch = [
+		compaction,
+		...(firstKeptIndex >= 0 ? branch.slice(firstKeptIndex, compactionIndex) : []),
+		...branch.slice(compactionIndex + 1),
+	];
+	return compactedBranch.map(entryToMessage).filter((message) => message !== undefined);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("handoff", {
+		description: "Summarize this session and continue in a fresh one",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			let rest = args.trim();
+			let auto = false;
+			if (rest.startsWith("mode:auto")) {
+				auto = true;
+				rest = rest.slice("mode:auto".length).trim();
+			}
+			if (!rest) {
+				ctx.ui.notify("Usage: /handoff [mode:auto] <goal for next session>", "error");
+				return;
+			}
+			const goal = rest;
+
+			const messages = getHandoffMessages(ctx.sessionManager.getBranch());
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			const conversationText = serializeConversation(convertToLlm(messages));
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			const generated = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+				const loader = new BorderedLoader(tui, theme, "Generating handoff prompt...");
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const userMessage: Message = {
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+							},
+						],
+						timestamp: Date.now(),
+					};
+
+					const response = await ctx.modelRegistry.complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ signal: loader.signal, cacheRetention: "none", sessionId: uuidv7() },
+					);
+
+					if (response.stopReason === "aborted") return null;
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doGenerate()
+					.then(done)
+					.catch((err) => {
+						console.error("Handoff generation failed:", err);
+						done(null);
+					});
+
+				return loader;
+			});
+
+			if (generated === null) {
+				ctx.ui.notify("Handoff cancelled", "info");
+				return;
+			}
+
+			let prompt = generated;
+			if (!auto) {
+				const edited = await ctx.ui.editor("Edit handoff prompt", generated);
+				if (edited === undefined) {
+					ctx.ui.notify("Handoff cancelled", "info");
+					return;
+				}
+				prompt = edited;
+			}
+
+			const result = await ctx.newSession({
+				parentSession: currentSessionFile,
+				withSession: async (replacementCtx) => {
+					if (auto) {
+						await replacementCtx.sendUserMessage(prompt, { expandPromptTemplates: true });
+					} else {
+						replacementCtx.ui.setEditorText(prompt);
+						replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
+					}
+				},
+			});
+
+			if (result.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+			}
+		},
+	});
+}

package/extensions/subagent/agents.ts

@@ -0,0 +1,160 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+	systemPrompt: string;
+	source: "user" | "project";
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+/**
+ * Raw agent frontmatter. Values are `unknown` because `parseFrontmatter` runs a
+ * real YAML parser, so any scalar or collection can appear here.
+ *
+ * A type alias rather than an interface: `parseFrontmatter` constrains its
+ * parameter to `Record<string, unknown>`, and only an alias picks up the
+ * implicit index signature that satisfies it.
+ */
+type AgentFrontmatter = {
+	name?: unknown;
+	description?: unknown;
+	tools?: unknown;
+	model?: unknown;
+	thinking?: unknown;
+};
+
+/**
+ * Normalize a frontmatter `tools` value to a list of tool names.
+ *
+ * Both spellings are valid YAML and both are in use:
+ *
+ *     tools: read, bash        # string
+ *     tools: [read, bash]      # array
+ *
+ * so accept either. Anything else (a number, a map, a nested list) yields no
+ * tools rather than throwing: this runs inside agent discovery, where a single
+ * bad file must not take down every other agent in the same directory.
+ */
+function parseToolList(value: unknown): string[] | undefined {
+	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+	const tools = raw
+		.filter((t): t is string => typeof t === "string")
+		.map((t) => t.trim())
+		.filter(Boolean);
+	return tools.length > 0 ? tools : undefined;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	if (!fs.existsSync(dir)) {
+		return agents;
+	}
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
+
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
+			continue;
+		}
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: parseToolList(frontmatter.tools),
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const agentMap = new Map<string, AgentConfig>();
+
+	if (scope === "both") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	} else if (scope === "user") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+	} else {
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	}
+
+	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}