@valni/cli-darwin-x64 0.0.0-stage → 0.1.3

package/runtime/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 "@valni/cli";
+
+export default function (valni: ExtensionAPI) {
+	const checkpoints = new Map<string, string>();
+	let currentEntryId: string | undefined;
+
+	// Track the current entry ID when user messages are saved
+	valni.on("tool_result", async (_event, ctx) => {
+		const leaf = ctx.sessionManager.getLeafEntry();
+		if (leaf) currentEntryId = leaf.id;
+	});
+
+	valni.on("turn_start", async () => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await valni.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref && currentEntryId) {
+			checkpoints.set(currentEntryId, ref);
+		}
+	});
+
+	valni.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 valni.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+	});
+
+	valni.on("agent_end", async () => {
+		// Clear checkpoints after agent completes
+		checkpoints.clear();
+	});
+}

package/runtime/examples/extensions/git-merge-and-resolve.ts

@@ -0,0 +1,115 @@
+/**
+ * Merge and Resolve
+ *
+ * Keeps the working branch up to date with its upstream tracking ref.
+ * After each agent turn, fetches and merges. Clean merges complete
+ * silently. When conflicts arise, the working tree is left dirty and
+ * the agent receives a follow-up message listing each conflict block
+ * with file, line range, and ours/theirs sections so it can resolve them.
+ * Also re-sends unresolved conflicts from a previous incomplete merge.
+ *
+ * Start valni with this extension:
+ *   valni -e ./examples/extensions/git-merge-and-resolve.ts
+ */
+import { createReadStream } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import type { ExtensionAPI } from "@valni/cli";
+
+interface ConflictBlock {
+	file: string;
+	startLine: number;
+	separatorLine: number;
+	endLine: number;
+}
+
+/** Parse conflict markers from working tree files with unmerged paths. */
+async function findConflicts(valni: ExtensionAPI, cwd: string): Promise<ConflictBlock[]> {
+	const { stdout, code } = await valni.exec("git", ["diff", "--name-only", "--diff-filter=U"]);
+	if (code !== 0 || !stdout.trim()) return [];
+
+	const blocks: ConflictBlock[] = [];
+	for (const file of stdout.trim().split("\n")) {
+		try {
+			const rl = createInterface({ input: createReadStream(join(cwd, file), "utf-8") });
+			let lineNo = 0;
+			let blockStart: number | undefined;
+			let separatorLine: number | undefined;
+			for await (const line of rl) {
+				lineNo++;
+				if (line.startsWith("<<<<<<<")) {
+					blockStart = lineNo;
+					separatorLine = undefined;
+				} else if (line.startsWith("=======") && blockStart !== undefined) {
+					separatorLine = lineNo;
+				} else if (line.startsWith(">>>>>>>") && blockStart !== undefined && separatorLine !== undefined) {
+					blocks.push({ file, startLine: blockStart, separatorLine, endLine: lineNo });
+					blockStart = undefined;
+					separatorLine = undefined;
+				}
+			}
+		} catch {}
+	}
+	return blocks;
+}
+
+function formatRange(start: number, end: number): string {
+	if (start > end) return "empty";
+	if (start === end) return `${start}`;
+	return `${start}-${end}`;
+}
+
+function formatConflicts(ref: string, blocks: ConflictBlock[]): string {
+	const lines = [`Merged ${ref} with conflicts:`, ""];
+	for (const b of blocks) {
+		const ours = formatRange(b.startLine + 1, b.separatorLine - 1);
+		const theirs = formatRange(b.separatorLine + 1, b.endLine - 1);
+		lines.push(`  ${b.file}:${b.startLine}-${b.endLine} (ours ${ours}, theirs ${theirs})`);
+	}
+	lines.push("", "Resolve these conflicts.");
+	return lines.join("\n");
+}
+
+export default function (valni: ExtensionAPI) {
+	valni.on("agent_end", async (_event, ctx) => {
+		const { code: revParseCode } = await valni.exec("git", ["rev-parse", "--git-dir"]);
+		if (revParseCode !== 0) return;
+
+		let ref = "MERGE_HEAD";
+
+		// If not already in a merge, attempt one
+		const { code: mergeHeadCode } = await valni.exec("git", ["rev-parse", "MERGE_HEAD"]);
+		if (mergeHeadCode !== 0) {
+			// Only attempt a new merge if the working tree is clean
+			const { stdout: status } = await valni.exec("git", ["status", "--porcelain"]);
+			if (status.trim()) return;
+
+			const { stdout: upstream, code: upstreamCode } = await valni.exec("git", [
+				"rev-parse",
+				"--abbrev-ref",
+				"--symbolic-full-name",
+				"@{u}",
+			]);
+			if (upstreamCode !== 0) return;
+
+			ref = upstream.trim();
+			const remote = ref.split("/")[0];
+			ctx.ui.notify(`git-merge-and-resolve: fetching ${remote}, merging ${ref}`, "info");
+
+			const { code: fetchCode, stderr: fetchErr } = await valni.exec("git", ["fetch", remote]);
+			if (fetchCode !== 0) {
+				ctx.ui.notify(`git-merge-and-resolve: fetch failed: ${fetchErr.trim()}`, "warning");
+				return;
+			}
+
+			const { code: mergeCode } = await valni.exec("git", ["merge", "--no-ff", ref]);
+			if (mergeCode === 0) return;
+		}
+
+		// Either we just merged with conflicts, or we were already in an unfinished merge
+		const conflicts = await findConflicts(valni, ctx.cwd);
+		if (conflicts.length === 0) return;
+
+		valni.sendUserMessage(formatConflicts(ref, conflicts), { deliverAs: "followUp" });
+	});
+}

package/runtime/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 "@valni/cli";
+import {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	type AutocompleteSuggestions,
+	fuzzyFilter,
+} from "@valni/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(valni: ExtensionAPI, cwd: string): Promise<RepoResolution> {
+	const result = await valni.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 (valni: ExtensionAPI): void {
+	valni.on("session_start", async (_event, ctx) => {
+		const resolvedRepo = await resolveGitHubRepo(valni, 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 valni.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/runtime/examples/extensions/hello.ts

@@ -0,0 +1,26 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ */
+
+import { Type } from "@valni/ai";
+import { defineTool, type ExtensionAPI } from "@valni/cli";
+
+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 (valni: ExtensionAPI) {
+	valni.registerTool(helloTool);
+}

package/runtime/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:
+ *   valni --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 "@valni/cli";
+
+const DEFAULT_LABEL = "Pondering...";
+
+export default function (valni: ExtensionAPI) {
+	let label = DEFAULT_LABEL;
+
+	const applyLabel = (ctx: ExtensionContext) => {
+		ctx.ui.setHiddenThinkingLabel(label);
+	};
+
+	valni.on("session_start", async (_event, ctx) => {
+		applyLabel(ctx);
+	});
+
+	valni.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}`);
+		},
+	});
+}

package/runtime/examples/extensions/inline-bash.ts

@@ -0,0 +1,94 @@
+/**
+ * Inline Bash Extension - expands inline bash commands in user prompts.
+ *
+ * Start valni with this extension:
+ *   valni -e ./examples/extensions/inline-bash.ts
+ *
+ * Then type prompts with inline bash:
+ *   What's in !{pwd}?
+ *   The current branch is !{git branch --show-current} and status: !{git status --short}
+ *   My node version is !{node --version}
+ *
+ * The !{command} patterns are executed and replaced with their output before
+ * the prompt is sent to the agent.
+ *
+ * Note: Regular !command syntax (whole-line bash) is preserved and works as before.
+ */
+import type { ExtensionAPI } from "@valni/cli";
+
+export default function (valni: ExtensionAPI) {
+	const PATTERN = /!\{([^}]+)\}/g;
+	const TIMEOUT_MS = 30000;
+
+	valni.on("input", async (event, ctx) => {
+		const text = event.text;
+
+		// Don't process if it's a whole-line bash command (starts with !)
+		// This preserves the existing !command behavior
+		if (text.trimStart().startsWith("!") && !text.trimStart().startsWith("!{")) {
+			return { action: "continue" };
+		}
+
+		// Check if there are any inline bash patterns
+		if (!PATTERN.test(text)) {
+			return { action: "continue" };
+		}
+
+		// Reset regex state after test()
+		PATTERN.lastIndex = 0;
+
+		let result = text;
+		const expansions: Array<{ command: string; output: string; error?: string }> = [];
+
+		// Find all matches first (to avoid issues with replacing while iterating)
+		const matches: Array<{ full: string; command: string }> = [];
+		let match = PATTERN.exec(text);
+		while (match) {
+			matches.push({ full: match[0], command: match[1] });
+			match = PATTERN.exec(text);
+		}
+
+		// Execute each command and collect results
+		for (const { full, command } of matches) {
+			try {
+				const bashResult = await valni.exec("bash", ["-c", command], {
+					timeout: TIMEOUT_MS,
+				});
+
+				const output = bashResult.stdout || bashResult.stderr || "";
+				const trimmed = output.trim();
+
+				if (bashResult.code !== 0 && bashResult.stderr) {
+					expansions.push({
+						command,
+						output: trimmed,
+						error: `exit code ${bashResult.code}`,
+					});
+				} else {
+					expansions.push({ command, output: trimmed });
+				}
+
+				result = result.replace(full, trimmed);
+			} catch (err) {
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				expansions.push({ command, output: "", error: errorMsg });
+				result = result.replace(full, `[error: ${errorMsg}]`);
+			}
+		}
+
+		// Show what was expanded (if UI available)
+		if (ctx.hasUI && expansions.length > 0) {
+			const summary = expansions
+				.map((e) => {
+					const status = e.error ? ` (${e.error})` : "";
+					const preview = e.output.length > 50 ? `${e.output.slice(0, 50)}...` : e.output;
+					return `!{${e.command}}${status} -> "${preview}"`;
+				})
+				.join("\n");
+
+			ctx.ui.notify(`Expanded ${expansions.length} inline command(s):\n${summary}`, "info");
+		}
+
+		return { action: "transform", text: result, images: event.images };
+	});
+}

package/runtime/examples/extensions/input-transform-streaming.ts

@@ -0,0 +1,39 @@
+/**
+ * Streaming-Aware Input Gate
+ *
+ * Demonstrates `event.streamingBehavior` to skip expensive pre-processing
+ * during mid-stream steering, where low latency matters.
+ *
+ * This extension prepends `git diff --stat` output when the user mentions
+ * file changes, giving the model immediate context. During steering the
+ * exec call is skipped so the correction reaches the model without delay.
+ *
+ * Start valni with this extension:
+ *   valni -e ./examples/extensions/input-transform-streaming.ts
+ */
+import type { ExtensionAPI } from "@valni/cli";
+
+const TRIGGER = /\b(changes?|diff|modified)\b/i;
+
+export default function (valni: ExtensionAPI) {
+	valni.on("input", async (event) => {
+		// During steering, skip the exec call — corrections should be fast
+		if (event.streamingBehavior === "steer") {
+			return { action: "continue" };
+		}
+
+		if (!TRIGGER.test(event.text)) {
+			return { action: "continue" };
+		}
+
+		const { stdout, code } = await valni.exec("git", ["diff", "--stat"]);
+		if (code !== 0 || !stdout.trim()) {
+			return { action: "continue" };
+		}
+
+		return {
+			action: "transform",
+			text: `${event.text}\n\nCurrent uncommitted changes:\n\`\`\`\n${stdout.trim()}\n\`\`\``,
+		};
+	});
+}

package/runtime/examples/extensions/input-transform.ts

@@ -0,0 +1,43 @@
+/**
+ * Input Transform Example - demonstrates the `input` event for intercepting user input.
+ *
+ * Start valni with this extension:
+ *   valni -e ./examples/extensions/input-transform.ts
+ *
+ * Then type these inside valni:
+ *   ?quick What is TypeScript?  → "Respond briefly: What is TypeScript?"
+ *   ping                        → "pong" (instant, no LLM)
+ *   time                        → current time (instant, no LLM)
+ */
+import type { ExtensionAPI } from "@valni/cli";
+
+export default function (valni: ExtensionAPI) {
+	valni.on("input", async (event, ctx) => {
+		// Source-based logic: skip processing for extension-injected messages
+		if (event.source === "extension") {
+			return { action: "continue" };
+		}
+
+		// Transform: ?quick prefix for brief responses
+		if (event.text.startsWith("?quick ")) {
+			const query = event.text.slice(7).trim();
+			if (!query) {
+				ctx.ui.notify("Usage: ?quick <question>", "warning");
+				return { action: "handled" };
+			}
+			return { action: "transform", text: `Respond briefly in 1-2 sentences: ${query}` };
+		}
+
+		// Handle: instant responses without LLM (extension shows its own feedback)
+		if (event.text.toLowerCase() === "ping") {
+			ctx.ui.notify("pong", "info");
+			return { action: "handled" };
+		}
+		if (event.text.toLowerCase() === "time") {
+			ctx.ui.notify(new Date().toLocaleString(), "info");
+			return { action: "handled" };
+		}
+
+		return { action: "continue" };
+	});
+}