@eminent337/aery 0.1.59 → 0.1.60

package/examples/extensions/dynamic-tools.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionAPI } from "@eminent337/aery";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 const ECHO_PARAMS = Type.Object({
 	message: Type.String({ description: "Message to echo" }),
@@ -35,7 +35,7 @@ export default function dynamicToolsExtension(pi: ExtensionAPI) {
 			label,
 			description: `Echo a message with prefix: ${prefix}`,
 			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
-			promptGuidelines: ["Use this tool when the user asks for exact echo output."],
+			promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
 			parameters: ECHO_PARAMS,
 			async execute(_toolCallId, params) {
 				return {

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 "@eminent337/aery";
+import {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	type AutocompleteSuggestions,
+	fuzzyFilter,
+} from "@eminent337/aery-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

@@ -12,9 +12,9 @@
  * The generated prompt appears as a draft in the editor for review/editing.
  */
 
-import { complete, type Message } from "@eminent337/aery-ai";
 import type { ExtensionAPI, SessionEntry } from "@eminent337/aery";
 import { BorderedLoader, convertToLlm, serializeConversation } from "@eminent337/aery";
+import { complete, type Message } from "@eminent337/aery-ai";
 
 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:
 
@@ -135,19 +135,20 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			// Create new session with parent tracking
+			// 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");
-				return;
 			}
-
-			// Set the edited prompt in the main editor for submission
-			ctx.ui.setEditorText(editedPrompt);
-			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
 		},
 	});
 }

package/examples/extensions/hello.ts

@@ -2,8 +2,8 @@
  * Hello Tool - Minimal custom tool example
  */
 
-import { Type } from "@eminent337/aery-ai";
 import { defineTool, type ExtensionAPI } from "@eminent337/aery";
+import { Type } from "@eminent337/aery-ai";
 
 const helloTool = defineTool({
 	name: "hello",

package/examples/extensions/plan-mode/index.ts

@@ -12,9 +12,9 @@
  * - Progress tracking widget during execution
  */
 
-import type { AgentMessage } from "@eminent337/aery-core";
-import type { AssistantMessage, TextContent } from "@eminent337/aery-ai";
 import type { ExtensionAPI, ExtensionContext } from "@eminent337/aery";
+import type { AssistantMessage, TextContent } from "@eminent337/aery-ai";
+import type { AgentMessage } from "@eminent337/aery-core";
 import { Key } from "@eminent337/aery-tui";
 import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.js";
 

package/examples/extensions/preset.ts

@@ -40,9 +40,9 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { Api, Model } from "@eminent337/aery-ai";
 import type { ExtensionAPI, ExtensionContext } from "@eminent337/aery";
 import { DynamicBorder, getAgentDir } from "@eminent337/aery";
+import type { Api, Model } from "@eminent337/aery-ai";
 import { Container, Key, type SelectItem, SelectList, Text } from "@eminent337/aery-tui";
 
 // Preset configuration

package/examples/extensions/prompt-customizer.ts

@@ -0,0 +1,97 @@
+/**
+ * Prompt Customizer Extension
+ *
+ * Demonstrates using systemPromptOptions to make informed, context-aware
+ * modifications to the system prompt without re-discovering resources.
+ *
+ * This extension adds tool-specific guidance based on what tools and skills
+ * are currently active, respecting whatever the user has configured.
+ *
+ * Usage:
+ * 1. Copy this file to ~/.aery/agent/extensions/ or your project's .pi/extensions/
+ * 2. Use the extension — it automatically adapts to your active tools and skills
+ */
+
+import type { BuildSystemPromptOptions, ExtensionAPI } from "@eminent337/aery";
+
+/**
+ * Adds tool-specific guidance that adapts to the active tool set.
+ * Instead of appending one-size-fits-all instructions, this reads what's
+ * actually loaded and tailors the guidance accordingly.
+ */
+function addToolGuidance(options: BuildSystemPromptOptions, basePrompt: string): string {
+	const hasTool = (name: string) => options.selectedTools?.includes(name) ?? false;
+
+	const parts: string[] = [];
+
+	if (hasTool("read")) {
+		parts.push(
+			"• Use the `read` tool for file contents (supports text and images).",
+			"  - For large files, use `offset` and `limit` to read in chunks.",
+		);
+	}
+
+	if (hasTool("bash")) {
+		parts.push("• Execute commands with the `bash` tool. Use it for file operations like `ls`, `find`, `grep`.");
+	}
+
+	if (hasTool("edit")) {
+		parts.push(
+			"• Use the `edit` tool for precise text replacements in files. Match exact content including whitespace.",
+		);
+	}
+
+	if (hasTool("write")) {
+		parts.push("• Use the `write` tool to create new files or overwrite existing ones completely.");
+	}
+
+	if (options.skills && options.skills.length > 0) {
+		const skillNames = options.skills.map((s) => s.name).join(", ");
+		parts.push(`\nAvailable skills: ${skillNames}`, "Use skill documentation for best practices on specific tools.");
+	}
+
+	if (parts.length === 0) {
+		return basePrompt;
+	}
+
+	return `${basePrompt}
+
+## Tool Guidance
+
+${parts.join("\n")}
+`;
+}
+
+/**
+ * Merges extension instructions with user-provided append prompts.
+ * This respects whatever the user configured via --append-system-prompt
+ * flags or files, rather than duplicating that work.
+ */
+function mergeWithUserAppend(options: BuildSystemPromptOptions): string {
+	const userAppend = options.appendSystemPrompt;
+	const extensionSpecific = `
+## Extension-Added Context
+
+This prompt includes tool guidance and skill information loaded dynamically.
+If you have additional requirements, configure them via --append-system-prompt or project context files.
+`;
+
+	if (userAppend) {
+		return `${userAppend}\n\n${extensionSpecific}`;
+	}
+
+	return extensionSpecific;
+}
+
+export default function promptCustomizer(pi: ExtensionAPI) {
+	pi.on("before_agent_start", async (event) => {
+		const { systemPrompt, systemPromptOptions } = event;
+
+		const customPrompt = addToolGuidance(systemPromptOptions, systemPrompt);
+		const appendSection = mergeWithUserAppend(systemPromptOptions);
+
+		return {
+			systemPrompt: `${customPrompt}${appendSection}`,
+		};
+	});
+}

package/examples/extensions/qna.ts

@@ -7,9 +7,9 @@
  * 3. Loads the result into the editor for user to fill in answers
  */
 
-import { complete, type UserMessage } from "@eminent337/aery-ai";
 import type { ExtensionAPI } from "@eminent337/aery";
 import { BorderedLoader } from "@eminent337/aery";
+import { complete, type UserMessage } from "@eminent337/aery-ai";
 
 const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
 

package/examples/extensions/question.ts

@@ -6,7 +6,7 @@
 
 import type { ExtensionAPI } from "@eminent337/aery";
 import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@eminent337/aery-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 interface OptionWithDesc {
 	label: string;

package/examples/extensions/questionnaire.ts

@@ -7,7 +7,7 @@
 
 import type { ExtensionAPI } from "@eminent337/aery";
 import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@eminent337/aery-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 // Types
 interface QuestionOption {

package/examples/extensions/reload-runtime.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ExtensionAPI } from "@eminent337/aery";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
 	// Command entrypoint for reload.

package/examples/extensions/shutdown-command.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ExtensionAPI } from "@eminent337/aery";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
 	// Register a /quit command that cleanly exits pi

package/examples/extensions/structured-output.ts

@@ -0,0 +1,65 @@
+/**
+ * Structured Output Tool
+ *
+ * Demonstrates `terminate: true` so the agent can end on a tool call
+ * without paying for an extra follow-up LLM turn.
+ */
+
+import { defineTool, type ExtensionAPI } from "@eminent337/aery";
+import { Text } from "@eminent337/aery-tui";
+import { Type } from "typebox";
+
+interface StructuredOutputDetails {
+	headline: string;
+	summary: string;
+	actionItems: string[];
+}
+
+const structuredOutputTool = defineTool({
+	name: "structured_output",
+	label: "Structured Output",
+	description:
+		"Return a final structured answer. Use this as your last action when the user asks for structured output or a machine-readable summary.",
+	promptSnippet: "Emit a final structured answer as a terminating tool result",
+	promptGuidelines: [
+		"Use structured_output as your final action when the user asks for structured output, JSON-like output, or a machine-readable summary.",
+		"After calling structured_output, do not emit another assistant response in the same turn.",
+	],
+	parameters: Type.Object({
+		headline: Type.String({ description: "Short title for the result" }),
+		summary: Type.String({ description: "One-paragraph summary" }),
+		actionItems: Type.Array(Type.String(), { description: "Concrete next steps or key bullets" }),
+	}),
+
+	async execute(_toolCallId, params) {
+		return {
+			content: [{ type: "text", text: `Saved structured output: ${params.headline}` }],
+			details: {
+				headline: params.headline,
+				summary: params.summary,
+				actionItems: params.actionItems,
+			} satisfies StructuredOutputDetails,
+			terminate: true,
+		};
+	},
+
+	renderResult(result, _options, theme) {
+		const details = result.details as StructuredOutputDetails | undefined;
+		if (!details) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "", 0, 0);
+		}
+
+		const lines = [
+			theme.fg("toolTitle", theme.bold(details.headline)),
+			theme.fg("text", details.summary),
+			"",
+			...details.actionItems.map((item, index) => theme.fg("muted", `${index + 1}. ${item}`)),
+		];
+		return new Text(lines.join("\n"), 0, 0);
+	},
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(structuredOutputTool);
+}

package/examples/extensions/subagent/index.ts

@@ -16,12 +16,12 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentToolResult } from "@eminent337/aery-core";
+import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@eminent337/aery";
 import type { Message } from "@eminent337/aery-ai";
 import { StringEnum } from "@eminent337/aery-ai";
-import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@eminent337/aery";
+import type { AgentToolResult } from "@eminent337/aery-core";
 import { Container, Markdown, Spacer, Text } from "@eminent337/aery-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
 
 const MAX_PARALLEL_TASKS = 8;

package/examples/extensions/summarize.ts

@@ -1,6 +1,6 @@
-import { complete, getModel } from "@eminent337/aery-ai";
 import type { ExtensionAPI, ExtensionCommandContext } from "@eminent337/aery";
 import { DynamicBorder, getMarkdownTheme } from "@eminent337/aery";
+import { complete, getModel } from "@eminent337/aery-ai";
 import { Container, Markdown, matchesKey, Text } from "@eminent337/aery-tui";
 
 type ContentBlock = {

package/examples/extensions/tic-tac-toe.ts

@@ -17,10 +17,10 @@
  * separate variables. Only the agent cursor is ever exposed to the agent.
  */
 
-import { StringEnum } from "@eminent337/aery-ai";
 import type { ExtensionAPI, ExtensionContext, Theme, ToolExecutionMode } from "@eminent337/aery";
+import { StringEnum } from "@eminent337/aery-ai";
 import { type Component, matchesKey, Text, truncateToWidth, visibleWidth } from "@eminent337/aery-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 // Thrown from the tool on illegal actions. The agent runtime surfaces thrown
 // errors as tool errors (isError=true) without resetting any of our state.