@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/examples/extensions/doom-overlay/wad-finder.ts

@@ -1,51 +0,0 @@
-import { existsSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// Get the bundled WAD path (relative to this module)
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const BUNDLED_WAD = join(__dirname, "doom1.wad");
-const WAD_URL = "https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad";
-
-const DEFAULT_WAD_PATHS = ["./doom1.wad", "./DOOM1.WAD", "~/doom1.wad", "~/.doom/doom1.wad"];
-
-export function findWadFile(customPath?: string): string | null {
-	if (customPath) {
-		const resolved = resolve(customPath.replace(/^~/, process.env.HOME || ""));
-		if (existsSync(resolved)) return resolved;
-		return null;
-	}
-
-	// Check bundled WAD first
-	if (existsSync(BUNDLED_WAD)) {
-		return BUNDLED_WAD;
-	}
-
-	// Fall back to default paths
-	for (const p of DEFAULT_WAD_PATHS) {
-		const resolved = resolve(p.replace(/^~/, process.env.HOME || ""));
-		if (existsSync(resolved)) return resolved;
-	}
-
-	return null;
-}
-
-/** Download the shareware WAD if not present. Returns path or null on failure. */
-export async function ensureWadFile(): Promise<string | null> {
-	// Check if already exists
-	const existing = findWadFile();
-	if (existing) return existing;
-
-	// Download to bundled location
-	try {
-		const response = await fetch(WAD_URL);
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status}`);
-		}
-		const buffer = await response.arrayBuffer();
-		writeFileSync(BUNDLED_WAD, Buffer.from(buffer));
-		return BUNDLED_WAD;
-	} catch {
-		return null;
-	}
-}

package/examples/extensions/dynamic-resources/SKILL.md

@@ -1,8 +0,0 @@
----
-name: dynamic-resources
-description: Example skill loaded from resources_discover
----
-
-# Dynamic Resources Skill
-
-This skill is provided by the dynamic-resources extension.

package/examples/extensions/dynamic-resources/dynamic.json

@@ -1,79 +0,0 @@
-{
-	"$schema": "https://raw.githubusercontent.com/f5xc-salesdemos/xcsh/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
-	"name": "dynamic-resources",
-	"vars": {
-		"cyan": "#00d7ff",
-		"blue": "#5f87ff",
-		"green": "#b5bd68",
-		"red": "#cc6666",
-		"yellow": "#ffff00",
-		"gray": "#808080",
-		"dimGray": "#666666",
-		"darkGray": "#505050",
-		"accent": "#8abeb7",
-		"selectedBg": "#3a3a4a",
-		"userMsgBg": "#343541",
-		"toolPendingBg": "#282832",
-		"toolSuccessBg": "#283228",
-		"toolErrorBg": "#3c2828",
-		"customMsgBg": "#2d2838"
-	},
-	"colors": {
-		"accent": "accent",
-		"border": "blue",
-		"borderAccent": "cyan",
-		"borderMuted": "darkGray",
-		"success": "green",
-		"error": "red",
-		"warning": "yellow",
-		"muted": "gray",
-		"dim": "dimGray",
-		"text": "",
-		"thinkingText": "gray",
-		"selectedBg": "selectedBg",
-		"userMessageBg": "userMsgBg",
-		"userMessageText": "",
-		"customMessageBg": "customMsgBg",
-		"customMessageText": "",
-		"customMessageLabel": "#9575cd",
-		"toolPendingBg": "toolPendingBg",
-		"toolSuccessBg": "toolSuccessBg",
-		"toolErrorBg": "toolErrorBg",
-		"toolTitle": "",
-		"toolOutput": "gray",
-		"mdHeading": "#f0c674",
-		"mdLink": "#81a2be",
-		"mdLinkUrl": "dimGray",
-		"mdCode": "accent",
-		"mdCodeBlock": "green",
-		"mdCodeBlockBorder": "gray",
-		"mdQuote": "gray",
-		"mdQuoteBorder": "gray",
-		"mdHr": "gray",
-		"mdListBullet": "accent",
-		"toolDiffAdded": "green",
-		"toolDiffRemoved": "red",
-		"toolDiffContext": "gray",
-		"syntaxComment": "#6A9955",
-		"syntaxKeyword": "#569CD6",
-		"syntaxFunction": "#DCDCAA",
-		"syntaxVariable": "#9CDCFE",
-		"syntaxString": "#CE9178",
-		"syntaxNumber": "#B5CEA8",
-		"syntaxType": "#4EC9B0",
-		"syntaxOperator": "#D4D4D4",
-		"syntaxPunctuation": "#D4D4D4",
-		"thinkingOff": "darkGray",
-		"thinkingMinimal": "#6e6e6e",
-		"thinkingLow": "#5f87af",
-		"thinkingMedium": "#81a2be",
-		"thinkingHigh": "#b294bb",
-		"thinkingXhigh": "#d183e8",
-		"bashMode": "green"
-	},
-	"export": {
-		"pageBg": "#18181e",
-		"cardBg": "#1e1e24",
-		"infoBg": "#3c3728"
-	}
-}

package/examples/extensions/dynamic-resources/dynamic.md

@@ -1,5 +0,0 @@
----
-description: Example prompt template loaded from resources_discover
----
-
-Summarize the current repository structure and mention any build or test commands.

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

@@ -1,15 +0,0 @@
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@f5xc-salesdemos/xcsh";
-
-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

@@ -1,74 +0,0 @@
-/**
- * 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 "@f5xc-salesdemos/xcsh";
-import { Type } from "@sinclair/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 this tool 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

@@ -1,43 +0,0 @@
-/**
- * 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 "@f5xc-salesdemos/xcsh";
-
-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

@@ -1,41 +0,0 @@
-/**
- * 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 "@f5xc-salesdemos/xcsh";
-
-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

@@ -1,53 +0,0 @@
-/**
- * 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 "@f5xc-salesdemos/xcsh";
-
-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/handoff.ts

@@ -1,153 +0,0 @@
-/**
- * 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 { ExtensionAPI, SessionEntry } from "@f5xc-salesdemos/xcsh";
-import { BorderedLoader, convertToLlm, serializeConversation } from "@f5xc-salesdemos/xcsh";
-import { complete, type Message } from "@f5xc-salesdemos/xcsh-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:
-
-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]`;
-
-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
-			const branch = ctx.sessionManager.getBranch();
-			const messages = branch
-				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-				.map((entry) => entry.message);
-
-			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
-			const newSessionResult = await ctx.newSession({
-				parentSession: currentSessionFile,
-			});
-
-			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/hidden-thinking-label.ts

@@ -1,53 +0,0 @@
-/**
- * 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 "@f5xc-salesdemos/xcsh";
-
-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}`);
-		},
-	});
-}

package/examples/extensions/inline-bash.ts

@@ -1,94 +0,0 @@
-/**
- * Inline Bash Extension - expands inline bash commands in user prompts.
- *
- * Start pi with this extension:
- *   pi -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 "@f5xc-salesdemos/xcsh";
-
-export default function (pi: ExtensionAPI) {
-	const PATTERN = /!\{([^}]+)\}/g;
-	const TIMEOUT_MS = 30000;
-
-	pi.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 pi.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 };
-	});
-}