@bastani/atomic 0.7.17 → 0.8.0

package/examples/extensions/dynamic-resources/index.ts

@@ -0,0 +1,15 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+export default function (pi: ExtensionAPI) {
+	pi.on("resources_discover", () => {
+		return {
+			skillPaths: [join(baseDir, "SKILL.md")],
+			promptPaths: [join(baseDir, "dynamic.md")],
+			themePaths: [join(baseDir, "dynamic.json")],
+		};
+	});
+}

package/examples/extensions/dynamic-tools.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const ECHO_PARAMS = Type.Object({
+	message: Type.String({ description: "Message to echo" }),
+});
+
+function normalizeToolName(input: string): string | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (!trimmed) return undefined;
+	if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export default function dynamicToolsExtension(pi: ExtensionAPI) {
+	const registeredToolNames = new Set<string>();
+
+	const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+		if (registeredToolNames.has(name)) {
+			return false;
+		}
+
+		registeredToolNames.add(name);
+		pi.registerTool({
+			name,
+			label,
+			description: `Echo a message with prefix: ${prefix}`,
+			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+			promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
+			parameters: ECHO_PARAMS,
+			async execute(_toolCallId, params) {
+				return {
+					content: [{ type: "text", text: `${prefix}${params.message}` }],
+					details: { tool: name, prefix },
+				};
+			},
+		});
+
+		return true;
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		registerEchoTool("echo_session", "Echo Session", "[session] ");
+		ctx.ui.notify("Registered dynamic tool: echo_session", "info");
+	});
+
+	pi.registerCommand("add-echo-tool", {
+		description: "Register a new echo tool dynamically: /add-echo-tool <tool_name>",
+		handler: async (args, ctx) => {
+			const toolName = normalizeToolName(args);
+			if (!toolName) {
+				ctx.ui.notify("Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)", "warning");
+				return;
+			}
+
+			const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+			if (!created) {
+				ctx.ui.notify(`Tool already registered: ${toolName}`, "warning");
+				return;
+			}
+
+			ctx.ui.notify(`Registered dynamic tool: ${toolName}`, "info");
+		},
+	});
+}

package/examples/extensions/event-bus.ts

@@ -0,0 +1,43 @@
+/**
+ * Inter-extension event bus example.
+ *
+ * Shows pi.events for communication between extensions. One extension
+ * can emit events that other extensions listen to.
+ *
+ * Usage: /emit [event-name] [data] - emit an event on the bus
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	// Store ctx for use in event handler
+	let currentCtx: ExtensionContext | undefined;
+
+	pi.on("session_start", async (_event, ctx) => {
+		currentCtx = ctx;
+	});
+
+	// Listen for events from other extensions
+	pi.events.on("my:notification", (data) => {
+		const { message, from } = data as { message: string; from: string };
+		currentCtx?.ui.notify(`Event from ${from}: ${message}`, "info");
+	});
+
+	// Command to emit events (emits "my:notification" which the listener above receives)
+	pi.registerCommand("emit", {
+		description: "Emit my:notification event (usage: /emit message)",
+		handler: async (args, _ctx) => {
+			const message = args.trim() || "hello";
+			pi.events.emit("my:notification", { message, from: "/emit command" });
+			// Listener above will show the notification
+		},
+	});
+
+	// Example: emit on session start
+	pi.on("session_start", async () => {
+		pi.events.emit("my:notification", {
+			message: "Session started",
+			from: "event-bus-example",
+		});
+	});
+}

package/examples/extensions/file-trigger.ts

@@ -0,0 +1,41 @@
+/**
+ * File Trigger Extension
+ *
+ * Watches a trigger file and injects its contents into the conversation.
+ * Useful for external systems to send messages to the agent.
+ *
+ * Usage:
+ *   echo "Run the tests" > /tmp/agent-trigger.txt
+ */
+
+import * as fs from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		const triggerFile = "/tmp/agent-trigger.txt";
+
+		fs.watch(triggerFile, () => {
+			try {
+				const content = fs.readFileSync(triggerFile, "utf-8").trim();
+				if (content) {
+					pi.sendMessage(
+						{
+							customType: "file-trigger",
+							content: `External trigger: ${content}`,
+							display: true,
+						},
+						{ triggerTurn: true }, // triggerTurn - get LLM to respond
+					);
+					fs.writeFileSync(triggerFile, ""); // Clear after reading
+				}
+			} catch {
+				// File might not exist yet
+			}
+		});
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Watching ${triggerFile}`, "info");
+		}
+	});
+}

package/examples/extensions/git-checkpoint.ts

@@ -0,0 +1,53 @@
+/**
+ * Git Checkpoint Extension
+ *
+ * Creates git stash checkpoints at each turn so /fork can restore code state.
+ * When forking, offers to restore code to that point in history.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	const checkpoints = new Map<string, string>();
+	let currentEntryId: string | undefined;
+
+	// Track the current entry ID when user messages are saved
+	pi.on("tool_result", async (_event, ctx) => {
+		const leaf = ctx.sessionManager.getLeafEntry();
+		if (leaf) currentEntryId = leaf.id;
+	});
+
+	pi.on("turn_start", async () => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await pi.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref && currentEntryId) {
+			checkpoints.set(currentEntryId, ref);
+		}
+	});
+
+	pi.on("session_before_fork", async (event, ctx) => {
+		const ref = checkpoints.get(event.entryId);
+		if (!ref) return;
+
+		if (!ctx.hasUI) {
+			// In non-interactive mode, don't restore automatically
+			return;
+		}
+
+		const choice = await ctx.ui.select("Restore code state?", [
+			"Yes, restore code to that point",
+			"No, keep current code",
+		]);
+
+		if (choice?.startsWith("Yes")) {
+			await pi.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+	});
+
+	pi.on("agent_end", async () => {
+		// Clear checkpoints after agent completes
+		checkpoints.clear();
+	});
+}

package/examples/extensions/github-issue-autocomplete.ts

@@ -0,0 +1,185 @@
+// Requires GitHub CLI (`gh`) and a GitHub repository checkout.
+// Preloads the latest open issues once per session, then filters them locally for fast `#...` completion.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	type AutocompleteSuggestions,
+	fuzzyFilter,
+} from "@earendil-works/pi-tui";
+
+type GitHubIssue = {
+	number: number;
+	title: string;
+	state: string;
+};
+
+type RepoResolution = { ok: true; repo: string } | { ok: false; error: string };
+
+const MAX_ISSUES = 100;
+const MAX_SUGGESTIONS = 20;
+
+function extractIssueToken(textBeforeCursor: string): string | undefined {
+	const match = textBeforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
+	return match?.[1];
+}
+
+function parseGitHubRepo(remoteUrl: string): string | undefined {
+	const sshMatch = remoteUrl.match(/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
+	if (sshMatch) {
+		return sshMatch[1];
+	}
+
+	const httpsMatch = remoteUrl.match(/^https?:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	if (httpsMatch) {
+		return httpsMatch[1];
+	}
+
+	return undefined;
+}
+
+async function resolveGitHubRepo(pi: ExtensionAPI, cwd: string): Promise<RepoResolution> {
+	const result = await pi.exec("git", ["remote", "-v"], { cwd, timeout: 5_000 });
+	if (result.code !== 0) {
+		return { ok: false, error: "github-issue-autocomplete: cwd is not a git repository" };
+	}
+
+	for (const line of result.stdout.split("\n")) {
+		const columns = line.trim().split(/\s+/);
+		const remoteUrl = columns[1];
+		if (!remoteUrl) {
+			continue;
+		}
+		const repo = parseGitHubRepo(remoteUrl);
+		if (repo) {
+			return { ok: true, repo };
+		}
+	}
+
+	return { ok: false, error: "github-issue-autocomplete: cwd is not a GitHub repository" };
+}
+
+function formatIssueItem(issue: GitHubIssue): AutocompleteItem {
+	return {
+		value: `#${issue.number}`,
+		label: `#${issue.number}`,
+		description: `[${issue.state.toLowerCase()}] ${issue.title}`,
+	};
+}
+
+function filterIssues(issues: GitHubIssue[], query: string): AutocompleteItem[] {
+	if (!query.trim()) {
+		return issues.slice(0, MAX_SUGGESTIONS).map(formatIssueItem);
+	}
+
+	if (/^\d+$/.test(query)) {
+		const numericMatches = issues
+			.filter((issue) => String(issue.number).startsWith(query))
+			.slice(0, MAX_SUGGESTIONS)
+			.map(formatIssueItem);
+		if (numericMatches.length > 0) {
+			return numericMatches;
+		}
+	}
+
+	return fuzzyFilter(issues, query, (issue) => `${issue.number} ${issue.title}`)
+		.slice(0, MAX_SUGGESTIONS)
+		.map(formatIssueItem);
+}
+
+function createIssueAutocompleteProvider(
+	current: AutocompleteProvider,
+	getIssues: () => Promise<GitHubIssue[] | undefined>,
+): AutocompleteProvider {
+	return {
+		async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+			const currentLine = lines[cursorLine] ?? "";
+			const textBeforeCursor = currentLine.slice(0, cursorCol);
+			const token = extractIssueToken(textBeforeCursor);
+			if (token === undefined) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+
+			const issues = await getIssues();
+			if (options.signal.aborted || !issues || issues.length === 0) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+
+			const suggestions = filterIssues(issues, token);
+			if (suggestions.length === 0) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+
+			return {
+				items: suggestions,
+				prefix: `#${token}`,
+			};
+		},
+
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	};
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx) => {
+		const resolvedRepo = await resolveGitHubRepo(pi, ctx.cwd);
+		if (!resolvedRepo.ok) {
+			ctx.ui.notify(resolvedRepo.error, "error");
+			return;
+		}
+
+		const repo = resolvedRepo.repo;
+		let issuesPromise: Promise<GitHubIssue[] | undefined> | undefined;
+		let loadErrorShown = false;
+
+		const getIssues = async (): Promise<GitHubIssue[] | undefined> => {
+			issuesPromise ||= (async () => {
+				const result = await pi.exec(
+					"gh",
+					[
+						"issue",
+						"list",
+						"--repo",
+						repo,
+						"--state",
+						"open",
+						"--limit",
+						String(MAX_ISSUES),
+						"--json",
+						"number,title,state",
+					],
+					{ cwd: ctx.cwd, timeout: 5_000 },
+				);
+				if (result.code !== 0) {
+					if (!loadErrorShown) {
+						loadErrorShown = true;
+						const details = result.stderr.trim() || `exit code ${result.code}`;
+						ctx.ui.notify(`github-issue-autocomplete: failed to load issues: ${details}`, "error");
+					}
+					return undefined;
+				}
+
+				try {
+					return JSON.parse(result.stdout) as GitHubIssue[];
+				} catch {
+					if (!loadErrorShown) {
+						loadErrorShown = true;
+						ctx.ui.notify("github-issue-autocomplete: failed to parse gh issue list output", "error");
+					}
+					return undefined;
+				}
+			})();
+			return issuesPromise;
+		};
+
+		void getIssues();
+		ctx.ui.addAutocompleteProvider((current) => createIssueAutocompleteProvider(current, getIssues));
+	});
+}

package/examples/extensions/handoff.ts

@@ -0,0 +1,191 @@
+/**
+ * Handoff extension - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { complete, type Message } 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 relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+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: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			// Gather conversation context from current branch. If the branch was compacted,
+			// include the compaction summary plus entries from firstKeptEntryId onward.
+			const messages = getHandoffMessages(ctx.sessionManager.getBranch());
+
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			// Convert to LLM format and serialize
+			const llmMessages = convertToLlm(messages);
+			const conversationText = serializeConversation(llmMessages);
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Generate the handoff prompt with loader UI
+			const result = 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 auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
+
+					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 complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
+					);
+
+					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 (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt", result);
+
+			if (editedPrompt === undefined) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Create new session with parent tracking. Use the replacement-session
+			// context for post-switch UI work; the original ctx is stale after a
+			// successful session replacement.
+			const newSessionResult = await ctx.newSession({
+				parentSession: currentSessionFile,
+				withSession: async (replacementCtx) => {
+					replacementCtx.ui.setEditorText(editedPrompt);
+					replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
+				},
+			});
+
+			if (newSessionResult.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+			}
+		},
+	});
+}

package/examples/extensions/hello.ts

@@ -0,0 +1,26 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ */
+
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const helloTool = defineTool({
+	name: "hello",
+	label: "Hello",
+	description: "A simple greeting tool",
+	parameters: Type.Object({
+		name: Type.String({ description: "Name to greet" }),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: `Hello, ${params.name}!` }],
+			details: { greeted: params.name },
+		};
+	},
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(helloTool);
+}

package/examples/extensions/hidden-thinking-label.ts

@@ -0,0 +1,53 @@
+/**
+ * Hidden Thinking Label Extension
+ *
+ * Demonstrates `ctx.ui.setHiddenThinkingLabel()` for customizing the label shown
+ * when thinking blocks are hidden.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/hidden-thinking-label.ts
+ *
+ * Test:
+ *   1. Load this extension
+ *   2. Hide thinking blocks with Ctrl+T
+ *   3. Ask for something that produces reasoning output
+ *   4. The collapsed thinking block label will show the custom text
+ *
+ * Commands:
+ *   /thinking-label <text>   Set a custom hidden thinking label
+ *   /thinking-label          Reset to the default label
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_LABEL = "Pondering...";
+
+export default function (pi: ExtensionAPI) {
+	let label = DEFAULT_LABEL;
+
+	const applyLabel = (ctx: ExtensionContext) => {
+		ctx.ui.setHiddenThinkingLabel(label);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		applyLabel(ctx);
+	});
+
+	pi.registerCommand("thinking-label", {
+		description: "Set the hidden thinking label. Use without args to reset.",
+		handler: async (args, ctx) => {
+			const nextLabel = args.trim();
+
+			if (!nextLabel) {
+				label = DEFAULT_LABEL;
+				ctx.ui.setHiddenThinkingLabel();
+				ctx.ui.notify(`Hidden thinking label reset to: ${DEFAULT_LABEL}`);
+				return;
+			}
+
+			label = nextLabel;
+			ctx.ui.setHiddenThinkingLabel(label);
+			ctx.ui.notify(`Hidden thinking label set to: ${label}`);
+		},
+	});
+}