@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/examples/hooks/handoff.ts

@@ -0,0 +1,149 @@
+/**
+ * Handoff hook - 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 { complete, type Message } from "@f5xc-salesdemos/pi-ai";
+import type { HookAPI, SessionEntry } from "@f5xc-salesdemos/xcsh";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@f5xc-salesdemos/xcsh";
+
+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: HookAPI) {
+	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, done) => {
+				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+					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, 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 (ctrl+enter to submit, esc to cancel)", 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/hooks/permission-gate.ts

@@ -0,0 +1,33 @@
+/**
+ * Permission Gate Hook
+ *
+ * Prompts for confirmation before running potentially dangerous bash commands.
+ * Patterns checked: rm -rf, sudo, chmod/chown 777
+ */
+import type { HookAPI } from "@f5xc-salesdemos/xcsh";
+
+export default function (pi: HookAPI) {
+	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = event.input.command as string;
+		const isDangerous = dangerousPatterns.some(p => p.test(command));
+
+		if (isDangerous) {
+			if (!ctx.hasUI) {
+				// In non-interactive mode, block by default
+				return { block: true, reason: "Dangerous command blocked (no UI for confirmation)" };
+			}
+
+			const choice = await ctx.ui.select(`⚠️ Dangerous command:\n\n  ${command}\n\nAllow?`, ["Yes", "No"]);
+
+			if (choice !== "Yes") {
+				return { block: true, reason: "Blocked by user" };
+			}
+		}
+
+		return undefined;
+	});
+}

package/examples/hooks/protected-paths.ts

@@ -0,0 +1,29 @@
+/**
+ * Protected Paths Hook
+ *
+ * Blocks write and edit operations to protected paths.
+ * Useful for preventing accidental modifications to sensitive files.
+ */
+import type { HookAPI } from "@f5xc-salesdemos/xcsh";
+
+export default function (pi: HookAPI) {
+	const protectedPaths = [".env", ".git/", "node_modules/"];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "write" && event.toolName !== "edit") {
+			return undefined;
+		}
+
+		const path = event.input.path as string;
+		const isProtected = protectedPaths.some(p => path.includes(p));
+
+		if (isProtected) {
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Blocked write to protected path: ${path}`, "warning");
+			}
+			return { block: true, reason: `Path "${path}" is protected` };
+		}
+
+		return undefined;
+	});
+}

package/examples/hooks/qna.ts

@@ -0,0 +1,118 @@
+/**
+ * Q&A extraction hook - extracts questions from assistant responses
+ *
+ * Demonstrates the "prompt generator" pattern:
+ * 1. /qna command gets the last assistant message
+ * 2. Shows a spinner while extracting (hides editor)
+ * 3. Loads the result into the editor for user to fill in answers
+ */
+import { complete, type UserMessage } from "@f5xc-salesdemos/pi-ai";
+import type { HookAPI } from "@f5xc-salesdemos/xcsh";
+import { BorderedLoader } from "@f5xc-salesdemos/xcsh";
+
+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.
+
+Output format:
+- List each question on its own line, prefixed with "Q: "
+- After each question, add a blank line for the answer prefixed with "A: "
+- If no questions are found, output "No questions found in the last message."
+
+Example output:
+Q: What is your preferred database?
+A: 
+
+Q: Should we use TypeScript or JavaScript?
+A: 
+
+Keep questions in the order they appeared. Be concise.`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("qna", {
+		description: "Extract questions from last assistant message into editor",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("qna requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			// Find the last assistant message on the current branch
+			const branch = ctx.sessionManager.getBranch();
+			let lastAssistantText: string | undefined;
+
+			for (let i = branch.length - 1; i >= 0; i--) {
+				const entry = branch[i];
+				if (entry.type === "message") {
+					const msg = entry.message;
+					if ("role" in msg && msg.role === "assistant") {
+						if (msg.stopReason !== "stop") {
+							ctx.ui.notify(`Last assistant message incomplete (${msg.stopReason})`, "error");
+							return;
+						}
+						const textParts = msg.content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map(c => c.text);
+						if (textParts.length > 0) {
+							lastAssistantText = textParts.join("\n");
+							break;
+						}
+					}
+				}
+			}
+
+			if (!lastAssistantText) {
+				ctx.ui.notify("No assistant messages found", "error");
+				return;
+			}
+
+			// Run extraction with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Extracting questions using ${ctx.model!.id}…`);
+				loader.onAbort = () => done(null);
+
+				// Do the work
+				const doExtract = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const userMessage: UserMessage = {
+						role: "user",
+						content: [{ type: "text", text: lastAssistantText! }],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, 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");
+				};
+
+				doExtract()
+					.then(done)
+					.catch(() => done(null));
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			ctx.ui.setEditorText(result);
+			ctx.ui.notify("Questions loaded. Edit and submit when ready.", "info");
+		},
+	});
+}

package/examples/hooks/status-line.ts

@@ -0,0 +1,39 @@
+/**
+ * Status Line Hook
+ *
+ * Demonstrates ctx.ui.setStatus() for displaying persistent status text in the footer.
+ * Shows turn progress with themed colors.
+ */
+import type { HookAPI } from "@f5xc-salesdemos/xcsh";
+
+export default function (pi: HookAPI) {
+	let turnCount = 0;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+	});
+
+	pi.on("turn_start", async (_event, ctx) => {
+		turnCount++;
+		const theme = ctx.ui.theme;
+		const spinner = theme.fg("accent", "●");
+		const text = theme.fg("dim", ` Turn ${turnCount}…`);
+		ctx.ui.setStatus("status-demo", spinner + text);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		const check = theme.fg("success", "✓");
+		const text = theme.fg("dim", ` Turn ${turnCount} complete`);
+		ctx.ui.setStatus("status-demo", check + text);
+	});
+
+	pi.on("session_switch", async (event, ctx) => {
+		if (event.reason === "new") {
+			turnCount = 0;
+			const theme = ctx.ui.theme;
+			ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+		}
+	});
+}

package/examples/sdk/01-minimal.ts

@@ -1,22 +1,21 @@
 /**
  * Minimal SDK Usage
  *
- * Uses all defaults: discovers skills, extensions, tools, context files
+ * Uses all defaults: discovers skills, hooks, tools, context files
  * from cwd and ~/.xcsh/agent. Model chosen from settings or first available.
  */
-
 import { createAgentSession } from "@f5xc-salesdemos/xcsh";
 
 const { session } = await createAgentSession();
 
-session.subscribe((event) => {
+session.subscribe(event => {
 	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 		process.stdout.write(event.assistantMessageEvent.delta);
 	}
 });
 
 await session.prompt("What files are in the current directory?");
-session.state.messages.forEach((msg) => {
+session.state.messages.forEach(msg => {
 	console.log(msg);
 });
 console.log();

package/examples/sdk/02-custom-model.ts

@@ -3,13 +3,13 @@
  *
  * Shows how to select a specific model and thinking level.
  */
-
-import { AuthStorage, createAgentSession, ModelRegistry } from "@f5xc-salesdemos/xcsh";
-import { getModel } from "@f5xc-salesdemos/xcsh-ai";
+import { ThinkingLevel } from "@f5xc-salesdemos/pi-agent-core";
+import { getModel } from "@f5xc-salesdemos/pi-ai";
+import { createAgentSession, discoverAuthStorage, discoverModels } from "@f5xc-salesdemos/xcsh";
 
 // Set up auth storage and model registry
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const authStorage = await discoverAuthStorage();
+const modelRegistry = await discoverModels(authStorage);
 
 // Option 1: Find a specific built-in model by provider/id
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -24,21 +24,21 @@ if (customModel) {
 }
 
 // Option 3: Pick from available models (have valid API keys)
-const available = await modelRegistry.getAvailable();
+const available = modelRegistry.getAvailable();
 console.log(
 	"Available models:",
-	available.map((m) => `${m.provider}/${m.id}`),
+	available.map(m => `${m.provider}/${m.id}`),
 );
 
 if (available.length > 0) {
 	const { session } = await createAgentSession({
 		model: available[0],
-		thinkingLevel: "medium", // off, low, medium, high
+		thinkingLevel: ThinkingLevel.Medium, // off, low, medium, high
 		authStorage,
 		modelRegistry,
 	});
 
-	session.subscribe((event) => {
+	session.subscribe(event => {
 		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 			process.stdout.write(event.assistantMessageEvent.delta);
 		}

package/examples/sdk/03-custom-prompt.ts

@@ -3,24 +3,16 @@
  *
  * Shows how to replace or modify the default system prompt.
  */
-
-import { createAgentSession, DefaultResourceLoader, SessionManager } from "@f5xc-salesdemos/xcsh";
+import { createAgentSession, SessionManager } from "@f5xc-salesdemos/xcsh";
 
 // Option 1: Replace prompt entirely
-const loader1 = new DefaultResourceLoader({
-	systemPromptOverride: () => `You are a helpful assistant that speaks like a pirate.
-Always end responses with "Arrr!"`,
-	// Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from ~/.xcsh/agent or <cwd>/.xcsh.
-	appendSystemPromptOverride: () => [],
-});
-await loader1.reload();
-
 const { session: session1 } = await createAgentSession({
-	resourceLoader: loader1,
+	systemPrompt: `You are a helpful assistant that speaks like a pirate.
+Always end responses with "Arrr!"`,
 	sessionManager: SessionManager.inMemory(),
 });
 
-session1.subscribe((event) => {
+session1.subscribe(event => {
 	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 		process.stdout.write(event.assistantMessageEvent.delta);
 	}
@@ -30,21 +22,17 @@ console.log("=== Replace prompt ===");
 await session1.prompt("What is 2 + 2?");
 console.log("\n");
 
-// Option 2: Append instructions to the default prompt
-const loader2 = new DefaultResourceLoader({
-	appendSystemPromptOverride: (base) => [
-		...base,
-		"## Additional Instructions\n- Always be concise\n- Use bullet points when listing things",
-	],
-});
-await loader2.reload();
-
+// Option 2: Modify default prompt (receives default, returns modified)
 const { session: session2 } = await createAgentSession({
-	resourceLoader: loader2,
+	systemPrompt: defaultPrompt => `${defaultPrompt}
+
+## Additional Instructions
+- Always be concise
+- Use bullet points when listing things`,
 	sessionManager: SessionManager.inMemory(),
 });
 
-session2.subscribe((event) => {
+session2.subscribe(event => {
 	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 		process.stdout.write(event.assistantMessageEvent.delta);
 	}

package/examples/sdk/04-skills.ts

@@ -4,14 +4,17 @@
  * Skills provide specialized instructions loaded into the system prompt.
  * Discover, filter, merge, or replace them.
  */
+import { createAgentSession, discoverSkills, SessionManager, type Skill } from "@f5xc-salesdemos/xcsh";
 
-import {
-	createAgentSession,
-	createSyntheticSourceInfo,
-	DefaultResourceLoader,
-	SessionManager,
-	type Skill,
-} from "@f5xc-salesdemos/xcsh";
+// Discover all skills from cwd/.xcsh/skills, ~/.xcsh/agent/skills, etc.
+const { skills: allSkills } = await discoverSkills();
+console.log(
+	"Discovered skills:",
+	allSkills.map(s => s.name),
+);
+
+// Filter to specific skills
+const filteredSkills = allSkills.filter(s => s.name.includes("browser") || s.name.includes("search"));
 
 // Or define custom skills inline
 const customSkill: Skill = {
@@ -19,34 +22,22 @@ const customSkill: Skill = {
 	description: "Custom project instructions",
 	filePath: "/virtual/SKILL.md",
 	baseDir: "/virtual",
-	sourceInfo: createSyntheticSourceInfo("/virtual/SKILL.md", { source: "sdk" }),
-	disableModelInvocation: false,
+	source: "custom",
 };
 
-const loader = new DefaultResourceLoader({
-	skillsOverride: (current) => {
-		const filteredSkills = current.skills.filter((s) => s.name.includes("browser") || s.name.includes("search"));
-		return {
-			skills: [...filteredSkills, customSkill],
-			diagnostics: current.diagnostics,
-		};
-	},
-});
-await loader.reload();
-
-// Discover all skills from cwd/.xcsh/skills, ~/.xcsh/agent/skills, etc.
-const { skills: allSkills, diagnostics } = loader.getSkills();
-console.log(
-	"Discovered skills:",
-	allSkills.map((s) => s.name),
-);
-if (diagnostics.length > 0) {
-	console.log("Warnings:", diagnostics);
-}
-
+// Use filtered + custom skills
 await createAgentSession({
-	resourceLoader: loader,
+	skills: [...filteredSkills, customSkill],
 	sessionManager: SessionManager.inMemory(),
 });
 
-console.log("Session created with filtered skills");
+console.log(`Session created with ${filteredSkills.length + 1} skills`);
+
+// To disable all skills:
+// skills: []
+
+// To use discovery with filtering via settings:
+// discoverSkills(process.cwd(), undefined, {
+//   ignoredSkills: ["browser-tools"],  // glob patterns to exclude
+//   includeSkills: ["brave-*"],        // glob patterns to include (empty = all)
+// })

package/examples/sdk/06-extensions.ts

@@ -4,38 +4,30 @@
  * Extensions intercept agent events and can register custom tools.
  * They provide a unified system for extensions, custom tools, commands, and more.
  *
- * By default, extension files are discovered from:
- * - ~/.xcsh/agent/extensions/
- * - <cwd>/.xcsh/extensions/
+ * Extension files are discovered from:
+ * - ~/.xcsh/agent/extensions/ (legacy: ~/.pi/agent/extensions/)
+ * - <cwd>/.xcsh/extensions/ (legacy: <cwd>/.pi/extensions/)
  * - Paths specified in settings.json "extensions" array
+ * - Paths passed via --extension CLI flag
  *
  * An extension is a TypeScript file that exports a default function:
  *   export default function (pi: ExtensionAPI) { ... }
  */
+import { createAgentSession, SessionManager } from "@f5xc-salesdemos/xcsh";
 
-import { createAgentSession, DefaultResourceLoader, SessionManager } from "@f5xc-salesdemos/xcsh";
-
-// Extensions are discovered automatically from standard locations.
-// You can also add paths via settings.json or DefaultResourceLoader options.
-
-const resourceLoader = new DefaultResourceLoader({
-	additionalExtensionPaths: ["./my-logging-extension.ts", "./my-safety-extension.ts"],
-	extensionFactories: [
-		(pi) => {
-			pi.on("agent_start", () => {
-				console.log("[Inline Extension] Agent starting");
-			});
-		},
-	],
-});
-await resourceLoader.reload();
+// Extensions are loaded from disk, not passed inline to createAgentSession.
+// Use the discovery mechanism:
+//   1. Place extension files in ~/.xcsh/agent/extensions/ or .xcsh/extensions/
+//   2. Add paths to settings.json: { "extensions": ["./my-extension.ts"] }
+//   3. Use --extension flag: pi --extension ./my-extension.ts
 
+// To add additional extension paths beyond discovery:
 const { session } = await createAgentSession({
-	resourceLoader,
+	additionalExtensionPaths: ["./my-logging-extension.ts", "./my-safety-extension.ts"],
 	sessionManager: SessionManager.inMemory(),
 });
 
-session.subscribe((event) => {
+session.subscribe(event => {
 	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 		process.stdout.write(event.assistantMessageEvent.delta);
 	}
@@ -71,7 +63,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			input: Type.String(),
 		}),
-		execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => ({
+		execute: async (_toolCallId, params, _onUpdate, _ctx, _signal) => ({
 			content: [{ type: "text", text: \`Processed: \${params.input}\` }],
 			details: {},
 		}),