@greppleai/grip 0.0.0-stage → 0.1.3

package/examples/extensions/questionnaire.ts

@@ -0,0 +1,459 @@
+/**
+ * Questionnaire Tool - Unified tool for asking single or multiple questions
+ *
+ * Single question: simple options list
+ * Multiple questions: tab bar navigation between questions
+ */
+
+import type { AgentToolResult, ExtensionAPI } from "@greppleai/grip";
+import { Editor, type EditorTheme, Key, matchesKey, type SelectItem, Text, truncateToWidth } from "@greppleai/grip-tui";
+import { Type } from "typebox";
+
+// Types
+type QuestionOption = SelectItem;
+
+type RenderOption = QuestionOption & { isOther?: boolean };
+
+interface Question {
+	id: string;
+	label: string;
+	prompt: string;
+	options: QuestionOption[];
+	allowOther: boolean;
+}
+
+interface Answer {
+	id: string;
+	value: string;
+	label: string;
+	wasCustom: boolean;
+	index?: number;
+}
+
+interface QuestionnaireResult {
+	questions: Question[];
+	answers: Answer[];
+	cancelled: boolean;
+}
+
+// Schema
+const QuestionOptionSchema = Type.Object({
+	value: Type.String({ description: "The value returned when selected" }),
+	label: Type.String({ description: "Display label for the option" }),
+	description: Type.Optional(Type.String({ description: "Optional description shown below label" })),
+});
+
+const QuestionSchema = Type.Object({
+	id: Type.String({ description: "Unique identifier for this question" }),
+	label: Type.Optional(
+		Type.String({
+			description: "Short contextual label for tab bar, e.g. 'Scope', 'Priority' (defaults to Q1, Q2)",
+		}),
+	),
+	prompt: Type.String({ description: "The full question text to display" }),
+	options: Type.Array(QuestionOptionSchema, { description: "Available options to choose from" }),
+	allowOther: Type.Optional(Type.Boolean({ description: "Allow 'Type something' option (default: true)" })),
+});
+
+const QuestionnaireParams = Type.Object({
+	questions: Type.Array(QuestionSchema, { description: "Questions to ask the user" }),
+});
+
+function errorResult(message: string, questions: Question[] = []): AgentToolResult<QuestionnaireResult> {
+	return {
+		content: [{ type: "text", text: message }],
+		details: { questions, answers: [], cancelled: true },
+	};
+}
+
+export default function questionnaire(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "questionnaire",
+		label: "Questionnaire",
+		description:
+			"Ask the user one or more questions. Use for clarifying requirements, getting preferences, or confirming decisions. For single questions, shows a simple option list. For multiple questions, shows a tab-based interface.",
+		parameters: QuestionnaireParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) {
+				return errorResult("Error: UI not available (running in non-interactive mode)");
+			}
+			if (params.questions.length === 0) {
+				return errorResult("Error: No questions provided");
+			}
+
+			// Normalize questions with defaults
+			const questions: Question[] = params.questions.map((q, i) => ({
+				...q,
+				label: q.label || `Q${i + 1}`,
+				allowOther: q.allowOther !== false,
+			}));
+
+			const isMulti = questions.length > 1;
+			const totalTabs = questions.length + 1; // questions + Submit
+
+			const result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {
+				// State
+				let currentTab = 0;
+				let optionIndex = 0;
+				let inputMode = false;
+				let inputQuestionId: string | null = null;
+				let cachedLines: string[] | undefined;
+				const answers = new Map<string, Answer>();
+
+				// Editor for "Type something" option
+				const editorTheme: EditorTheme = {
+					borderColor: (s) => theme.fg("accent", s),
+					selectList: {
+						selectedPrefix: (t) => theme.fg("accent", t),
+						selectedText: (t) => theme.fg("accent", t),
+						description: (t) => theme.fg("muted", t),
+						scrollInfo: (t) => theme.fg("dim", t),
+						noMatch: (t) => theme.fg("warning", t),
+					},
+				};
+				const editor = new Editor(tui, editorTheme);
+
+				// Helpers
+				function refresh() {
+					cachedLines = undefined;
+					tui.requestRender();
+				}
+
+				function submit(cancelled: boolean) {
+					done({ questions, answers: Array.from(answers.values()), cancelled });
+				}
+
+				function currentQuestion(): Question | undefined {
+					return questions[currentTab];
+				}
+
+				function currentOptions(): RenderOption[] {
+					const q = currentQuestion();
+					if (!q) return [];
+					const opts: RenderOption[] = [...q.options];
+					if (q.allowOther) {
+						opts.push({ value: "__other__", label: "Type something.", isOther: true });
+					}
+					return opts;
+				}
+
+				function allAnswered(): boolean {
+					return questions.every((q) => answers.has(q.id));
+				}
+
+				function advanceAfterAnswer() {
+					if (!isMulti) {
+						submit(false);
+						return;
+					}
+					if (currentTab < questions.length - 1) {
+						currentTab++;
+					} else {
+						currentTab = questions.length; // Submit tab
+					}
+					optionIndex = 0;
+					refresh();
+				}
+
+				function saveAnswer(questionId: string, value: string, label: string, wasCustom: boolean, index?: number) {
+					answers.set(questionId, { id: questionId, value, label, wasCustom, index });
+				}
+
+				// Editor submit callback
+				editor.onSubmit = (value) => {
+					if (!inputQuestionId) return;
+					const trimmed = value.trim() || "(no response)";
+					saveAnswer(inputQuestionId, trimmed, trimmed, true);
+					inputMode = false;
+					inputQuestionId = null;
+					editor.setText("");
+					advanceAfterAnswer();
+				};
+
+				function handleEditorInput(data: string): boolean {
+					if (!inputMode) return false;
+					if (matchesKey(data, Key.escape)) {
+						inputMode = false;
+						inputQuestionId = null;
+						editor.setText("");
+						refresh();
+						return true;
+					}
+					editor.handleInput(data);
+					refresh();
+					return true;
+				}
+
+				function handleQuestionTabNavigation(data: string): boolean {
+					if (!isMulti) return false;
+					if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+						currentTab = (currentTab + 1) % totalTabs;
+					} else if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+						currentTab = (currentTab - 1 + totalTabs) % totalTabs;
+					} else {
+						return false;
+					}
+					optionIndex = 0;
+					refresh();
+					return true;
+				}
+
+				function handleSubmitTabInput(data: string): boolean {
+					if (currentTab !== questions.length) return false;
+					if (matchesKey(data, Key.enter) && allAnswered()) submit(false);
+					else if (matchesKey(data, Key.escape)) submit(true);
+					return true;
+				}
+
+				function handleOptionNavigation(data: string): boolean {
+					const options = currentOptions();
+					if (matchesKey(data, Key.up)) {
+						optionIndex = Math.max(0, optionIndex - 1);
+					} else if (matchesKey(data, Key.down)) {
+						optionIndex = Math.min(options.length - 1, optionIndex + 1);
+					} else {
+						return false;
+					}
+					refresh();
+					return true;
+				}
+
+				function handleOptionSelection(data: string): boolean {
+					const question = currentQuestion();
+					const options = currentOptions();
+					if (!matchesKey(data, Key.enter) || !question) return false;
+					const option = options[optionIndex];
+					if (option.isOther) {
+						inputMode = true;
+						inputQuestionId = question.id;
+						editor.setText("");
+						refresh();
+						return true;
+					}
+					saveAnswer(question.id, option.value, option.label, false, optionIndex + 1);
+					advanceAfterAnswer();
+					return true;
+				}
+
+				function handleQuestionnaireCancel(data: string): boolean {
+					if (!matchesKey(data, Key.escape)) return false;
+					submit(true);
+					return true;
+				}
+
+				const inputHandlers = [
+					handleEditorInput,
+					handleQuestionTabNavigation,
+					handleSubmitTabInput,
+					handleOptionNavigation,
+					handleOptionSelection,
+					handleQuestionnaireCancel,
+				];
+
+				function handleInput(data: string) {
+					for (const handler of inputHandlers) {
+						if (handler(data)) return;
+					}
+				}
+
+				function addLine(lines: string[], width: number, text: string): void {
+					lines.push(truncateToWidth(text, width));
+				}
+
+				function formatQuestionTab(question: Question, index: number): string {
+					const isActive = index === currentTab;
+					const isAnswered = answers.has(question.id);
+					const box = isAnswered ? "■" : "□";
+					const color = isAnswered ? "success" : "muted";
+					const text = ` ${box} ${question.label} `;
+					const styled = isActive ? theme.bg("selectedBg", theme.fg("text", text)) : theme.fg(color, text);
+					return `${styled} `;
+				}
+
+				function appendQuestionTabs(lines: string[], width: number): void {
+					if (!isMulti) return;
+					const tabs = ["← ", ...questions.map(formatQuestionTab)];
+					const submitText = " ✓ Submit ";
+					const submitStyled =
+						currentTab === questions.length
+							? theme.bg("selectedBg", theme.fg("text", submitText))
+							: theme.fg(allAnswered() ? "success" : "dim", submitText);
+					tabs.push(`${submitStyled} →`);
+					addLine(lines, width, ` ${tabs.join("")}`);
+					lines.push("");
+				}
+
+				function formatOptionLine(option: RenderOption, index: number): string {
+					const selected = index === optionIndex;
+					const prefix = selected ? theme.fg("accent", "> ") : "  ";
+					const color = selected ? "accent" : "text";
+					const label =
+						option.isOther && inputMode ? `${index + 1}. ${option.label} ✎` : `${index + 1}. ${option.label}`;
+					return prefix + theme.fg(color, label);
+				}
+
+				function appendOptions(lines: string[], width: number, options: RenderOption[]): void {
+					for (let index = 0; index < options.length; index++) {
+						const option = options[index];
+						addLine(lines, width, formatOptionLine(option, index));
+						if (option.description) addLine(lines, width, `     ${theme.fg("muted", option.description)}`);
+					}
+				}
+
+				function appendCustomAnswerInput(
+					lines: string[],
+					width: number,
+					question: Question,
+					options: RenderOption[],
+				): void {
+					addLine(lines, width, theme.fg("text", ` ${question.prompt}`));
+					lines.push("");
+					appendOptions(lines, width, options);
+					lines.push("");
+					addLine(lines, width, theme.fg("muted", " Your answer:"));
+					for (const line of editor.render(width - 2)) addLine(lines, width, ` ${line}`);
+					lines.push("");
+					addLine(lines, width, theme.fg("dim", " Enter to submit • Esc to cancel"));
+				}
+
+				function appendAnswerSummary(lines: string[], width: number): void {
+					for (const question of questions) {
+						const answer = answers.get(question.id);
+						if (!answer) continue;
+						const prefix = answer.wasCustom ? "(wrote) " : "";
+						addLine(
+							lines,
+							width,
+							`${theme.fg("muted", ` ${question.label}: `)}${theme.fg("text", prefix + answer.label)}`,
+						);
+					}
+				}
+
+				function appendSubmitPrompt(lines: string[], width: number): void {
+					if (allAnswered()) {
+						addLine(lines, width, theme.fg("success", " Press Enter to submit"));
+						return;
+					}
+					const missing = questions
+						.filter((question) => !answers.has(question.id))
+						.map((question) => question.label)
+						.join(", ");
+					addLine(lines, width, theme.fg("warning", ` Unanswered: ${missing}`));
+				}
+
+				function appendSubmissionSummary(lines: string[], width: number): void {
+					addLine(lines, width, theme.fg("accent", theme.bold(" Ready to submit")));
+					lines.push("");
+					appendAnswerSummary(lines, width);
+					lines.push("");
+					appendSubmitPrompt(lines, width);
+				}
+
+				function appendQuestionContent(
+					lines: string[],
+					width: number,
+					question: Question | undefined,
+					options: RenderOption[],
+				): void {
+					if (inputMode && question) {
+						appendCustomAnswerInput(lines, width, question, options);
+						return;
+					}
+					if (currentTab === questions.length) {
+						appendSubmissionSummary(lines, width);
+						return;
+					}
+					if (!question) return;
+					addLine(lines, width, theme.fg("text", ` ${question.prompt}`));
+					lines.push("");
+					appendOptions(lines, width, options);
+				}
+
+				function appendQuestionnaireHelp(lines: string[], width: number): void {
+					if (inputMode) return;
+					const help = isMulti
+						? " Tab/←→ navigate • ↑↓ select • Enter confirm • Esc cancel"
+						: " ↑↓ navigate • Enter select • Esc cancel";
+					addLine(lines, width, theme.fg("dim", help));
+				}
+
+				function render(width: number): string[] {
+					if (cachedLines) return cachedLines;
+					const lines: string[] = [];
+					addLine(lines, width, theme.fg("accent", "─".repeat(width)));
+					appendQuestionTabs(lines, width);
+					appendQuestionContent(lines, width, currentQuestion(), currentOptions());
+					lines.push("");
+					appendQuestionnaireHelp(lines, width);
+					addLine(lines, width, theme.fg("accent", "─".repeat(width)));
+					cachedLines = lines;
+					return lines;
+				}
+
+				return {
+					render,
+					invalidate: () => {
+						cachedLines = undefined;
+					},
+					handleInput,
+				};
+			});
+
+			if (result.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: result,
+				};
+			}
+
+			const firstQuestionLabelById = new Map<string, string>();
+			for (const question of questions) {
+				if (!firstQuestionLabelById.has(question.id)) firstQuestionLabelById.set(question.id, question.label);
+			}
+			const answerLines = result.answers.map((a) => {
+				const qLabel = firstQuestionLabelById.get(a.id) || a.id;
+				if (a.wasCustom) {
+					return `${qLabel}: user wrote: ${a.label}`;
+				}
+				return `${qLabel}: user selected: ${a.index}. ${a.label}`;
+			});
+
+			return {
+				content: [{ type: "text", text: answerLines.join("\n") }],
+				details: result,
+			};
+		},
+
+		renderCall(args, theme, _context) {
+			const qs = (args.questions as Question[]) || [];
+			const count = qs.length;
+			const labels = qs.map((q) => q.label || q.id).join(", ");
+			let text = theme.fg("toolTitle", theme.bold("questionnaire "));
+			text += theme.fg("muted", `${count} question${count !== 1 ? "s" : ""}`);
+			if (labels) {
+				text += theme.fg("dim", ` (${truncateToWidth(labels, 40)})`);
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme, _context) {
+			const details = result.details as QuestionnaireResult | undefined;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+			if (details.cancelled) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const lines = details.answers.map((a) => {
+				if (a.wasCustom) {
+					return `${theme.fg("success", "✓ ")}${theme.fg("accent", a.id)}: ${theme.fg("muted", "(wrote) ")}${a.label}`;
+				}
+				const display = a.index ? `${a.index}. ${a.label}` : a.label;
+				return `${theme.fg("success", "✓ ")}${theme.fg("accent", a.id)}: ${display}`;
+			});
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}

package/examples/extensions/rainbow-editor.ts

@@ -0,0 +1,88 @@
+/**
+ * Rainbow Editor - highlights "ultrathink" with animated shine effect
+ *
+ * Usage: grip --extension ./examples/extensions/rainbow-editor.ts
+ */
+
+import { CustomEditor, type ExtensionAPI } from "@greppleai/grip";
+
+// Base colors (coral → yellow → green → teal → blue → purple → pink)
+const COLORS: [number, number, number][] = [
+	[233, 137, 115], // coral
+	[228, 186, 103], // yellow
+	[141, 192, 122], // green
+	[102, 194, 179], // teal
+	[121, 157, 207], // blue
+	[157, 134, 195], // purple
+	[206, 130, 172], // pink
+];
+const RESET = "\x1b[0m";
+
+function brighten(rgb: [number, number, number], factor: number): string {
+	const [r, g, b] = rgb.map((c) => Math.round(c + (255 - c) * factor));
+	return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+function colorize(text: string, shinePos: number): string {
+	return (
+		[...text]
+			.map((c, i) => {
+				const baseColor = COLORS[i % COLORS.length]!;
+				// 3-letter shine: center bright, adjacent dimmer
+				let factor = 0;
+				if (shinePos >= 0) {
+					const dist = Math.abs(i - shinePos);
+					if (dist === 0) factor = 0.7;
+					else if (dist === 1) factor = 0.35;
+				}
+				return `${brighten(baseColor, factor)}${c}`;
+			})
+			.join("") + RESET
+	);
+}
+
+class RainbowEditor extends CustomEditor {
+	private animationTimer?: ReturnType<typeof setInterval>;
+	private frame = 0;
+
+	private hasUltrathink(): boolean {
+		return /ultrathink/i.test(this.getText());
+	}
+
+	private startAnimation(): void {
+		if (this.animationTimer) return;
+		this.animationTimer = setInterval(() => {
+			this.frame++;
+			this.tui.requestRender();
+		}, 60);
+	}
+
+	private stopAnimation(): void {
+		if (this.animationTimer) {
+			clearInterval(this.animationTimer);
+			this.animationTimer = undefined;
+		}
+	}
+
+	handleInput(data: string): void {
+		super.handleInput(data);
+		if (this.hasUltrathink()) {
+			this.startAnimation();
+		} else {
+			this.stopAnimation();
+		}
+	}
+
+	render(width: number): string[] {
+		// Cycle: 10 shine positions + 10 pause frames
+		const cycle = this.frame % 20;
+		const shinePos = cycle < 10 ? cycle : -1; // -1 means no shine (pause)
+		return super.render(width).map((line) => line.replace(/ultrathink/gi, (m) => colorize(m, shinePos)));
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui, theme, kb) => new RainbowEditor(tui, theme, kb));
+	});
+}

package/examples/extensions/reload-runtime.ts

@@ -0,0 +1,37 @@
+/**
+ * Reload Runtime Extension
+ *
+ * Demonstrates ctx.reload() from ExtensionCommandContext and an LLM-callable
+ * tool that queues a follow-up command to trigger reload.
+ */
+
+import type { ExtensionAPI } from "@greppleai/grip";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+	// Command entrypoint for reload.
+	// Treat reload as terminal for this handler.
+	pi.registerCommand("reload-runtime", {
+		description: "Reload extensions, skills, rules, prompts, and themes",
+		handler: async (_args, ctx) => {
+			await ctx.reload();
+			return;
+		},
+	});
+
+	// LLM-callable tool. Tools get ExtensionContext, so they cannot call ctx.reload() directly.
+	// Instead, queue a follow-up user command that executes the command above.
+	pi.registerTool({
+		name: "reload_runtime",
+		label: "Reload Runtime",
+		description: "Reload extensions, skills, rules, prompts, and themes",
+		parameters: Type.Object({}),
+		async execute() {
+			pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
+			return {
+				content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
+				details: {},
+			};
+		},
+	});
+}

package/examples/extensions/rpc-demo.ts

@@ -0,0 +1,118 @@
+/**
+ * RPC Extension UI Demo
+ *
+ * Purpose-built extension that exercises all RPC-supported extension UI methods.
+ * Designed to be loaded alongside the rpc-extension-ui-example.ts script to
+ * demonstrate the full extension UI protocol.
+ *
+ * UI methods exercised:
+ * - select() - on tool_call for dangerous bash commands
+ * - confirm() - on session_before_switch
+ * - input() - via /rpc-input command
+ * - editor() - via /rpc-editor command
+ * - notify() - after each dialog completes
+ * - setStatus() - on turn_start/turn_end
+ * - setWidget() - on session_start
+ * - setTitle() - on session_start
+ * - setEditorText() - via /rpc-prefill command
+ */
+
+import type { ExtensionAPI } from "@greppleai/grip";
+
+export default function (pi: ExtensionAPI) {
+	let turnCount = 0;
+
+	// -- setTitle, setWidget, setStatus on session lifecycle --
+
+	pi.on("session_start", async (event, ctx) => {
+		ctx.ui.setTitle(event.reason === "new" ? "grip RPC Demo (new session)" : "grip RPC Demo");
+		ctx.ui.setWidget("rpc-demo", ["--- RPC Extension UI Demo ---", "Loaded and ready."]);
+		ctx.ui.setStatus("rpc-demo", `Turns: ${turnCount}`);
+	});
+
+	// -- setStatus on turn lifecycle --
+
+	pi.on("turn_start", async (_event, ctx) => {
+		turnCount++;
+		ctx.ui.setStatus("rpc-demo", `Turn ${turnCount} running...`);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		ctx.ui.setStatus("rpc-demo", `Turn ${turnCount} done`);
+	});
+
+	// -- select on dangerous tool calls --
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = event.input.command as string;
+		const isDangerous = /\brm\s+(-rf?|--recursive)/i.test(command) || /\bsudo\b/i.test(command);
+
+		if (isDangerous) {
+			if (!ctx.hasUI) {
+				return { block: true, reason: "Dangerous command blocked (no UI)" };
+			}
+
+			const choice = await ctx.ui.select(`Dangerous command: ${command}`, ["Allow", "Block"]);
+			if (choice !== "Allow") {
+				ctx.ui.notify("Command blocked by user", "warning");
+				return { block: true, reason: "Blocked by user" };
+			}
+			ctx.ui.notify("Command allowed", "info");
+		}
+
+		return undefined;
+	});
+
+	// -- confirm on session clear --
+
+	pi.on("session_before_switch", async (event, ctx) => {
+		if (event.reason !== "new") return;
+		if (!ctx.hasUI) return;
+
+		const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
+		if (!confirmed) {
+			ctx.ui.notify("Clear cancelled", "info");
+			return { cancel: true };
+		}
+	});
+
+	// -- input via command --
+
+	pi.registerCommand("rpc-input", {
+		description: "Prompt for text input (demonstrates ctx.ui.input in RPC)",
+		handler: async (_args, ctx) => {
+			const value = await ctx.ui.input("Enter a value", "type something...");
+			if (value) {
+				ctx.ui.notify(`You entered: ${value}`, "info");
+			} else {
+				ctx.ui.notify("Input cancelled", "info");
+			}
+		},
+	});
+
+	// -- editor via command --
+
+	pi.registerCommand("rpc-editor", {
+		description: "Open multi-line editor (demonstrates ctx.ui.editor in RPC)",
+		handler: async (_args, ctx) => {
+			const text = await ctx.ui.editor("Edit some text", "Line 1\nLine 2\nLine 3");
+			if (text) {
+				ctx.ui.notify(`Editor submitted (${text.split("\n").length} lines)`, "info");
+			} else {
+				ctx.ui.notify("Editor cancelled", "info");
+			}
+		},
+	});
+
+	// -- setEditorText via command --
+
+	pi.registerCommand("rpc-prefill", {
+		description: "Prefill the input editor (demonstrates ctx.ui.setEditorText in RPC)",
+		handler: async (_args, ctx) => {
+			ctx.ui.setEditorText("This text was set by the rpc-demo extension.");
+			ctx.ui.notify("Editor prefilled", "info");
+		},
+	});
+}