@f5-sales-demo/xcsh 19.51.2

package/src/internal-urls/mcp-protocol.ts

@@ -0,0 +1,156 @@
+import type { MCPManager } from "../mcp/manager";
+import type { MCPResourceReadResult } from "../mcp/types";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface McpProtocolOptions {
+	getMcpManager: () => MCPManager | undefined;
+}
+
+function escapeRegex(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function getUriTemplateMatchScore(
+	uri: string,
+	uriTemplate: string,
+): { literalChars: number; expressionCount: number } | undefined {
+	const expressionPattern = /\{[^}]+\}/g;
+	const literalSegments = uriTemplate.split(expressionPattern);
+	const expressionCount = (uriTemplate.match(expressionPattern) ?? []).length;
+	const pattern = literalSegments.map(escapeRegex).join("(.*?)");
+	const regex = new RegExp(`^${pattern}$`);
+	if (!regex.test(uri)) return undefined;
+	const literalChars = literalSegments.reduce((total, segment) => total + segment.length, 0);
+	return { literalChars, expressionCount };
+}
+
+function extractResourceUri(url: InternalUrl): string {
+	const host = url.rawHost || url.hostname;
+	const rawPathname = url.rawPathname ?? url.pathname;
+	const hasPath = rawPathname && rawPathname !== "/";
+	const uri = `${host}${hasPath ? rawPathname : ""}${url.search}${url.hash}`.trim();
+	if (!uri) {
+		throw new Error("mcp:// URL requires a resource URI: mcp://<resource-uri>");
+	}
+	return uri;
+}
+
+function resolveTargetServer(mcpManager: MCPManager, uri: string): string | undefined {
+	const servers = mcpManager.getConnectedServers();
+	for (const name of servers) {
+		const serverResources = mcpManager.getServerResources(name);
+		if (serverResources?.resources.some(r => r.uri === uri)) {
+			return name;
+		}
+	}
+
+	let bestTemplateMatch:
+		| {
+				serverName: string;
+				literalChars: number;
+				expressionCount: number;
+				serverIndex: number;
+				templateIndex: number;
+		  }
+		| undefined;
+
+	for (const [serverIndex, name] of servers.entries()) {
+		const serverResources = mcpManager.getServerResources(name);
+		if (!serverResources) continue;
+
+		for (const [templateIndex, template] of serverResources.templates.entries()) {
+			const match = getUriTemplateMatchScore(uri, template.uriTemplate);
+			if (!match) continue;
+
+			const isBetterMatch =
+				!bestTemplateMatch ||
+				match.literalChars > bestTemplateMatch.literalChars ||
+				(match.literalChars === bestTemplateMatch.literalChars &&
+					(match.expressionCount < bestTemplateMatch.expressionCount ||
+						(match.expressionCount === bestTemplateMatch.expressionCount &&
+							(serverIndex < bestTemplateMatch.serverIndex ||
+								(serverIndex === bestTemplateMatch.serverIndex &&
+									templateIndex < bestTemplateMatch.templateIndex)))));
+
+			if (isBetterMatch) {
+				bestTemplateMatch = {
+					serverName: name,
+					literalChars: match.literalChars,
+					expressionCount: match.expressionCount,
+					serverIndex,
+					templateIndex,
+				};
+			}
+		}
+	}
+
+	return bestTemplateMatch?.serverName;
+}
+
+function formatAvailableResources(mcpManager: MCPManager): string {
+	const available = mcpManager
+		.getConnectedServers()
+		.flatMap(name => {
+			const serverResources = mcpManager.getServerResources(name);
+			return (serverResources?.resources ?? []).map(r => `  ${r.uri} (${name})`);
+		})
+		.join("\n");
+	return available || "  (none)";
+}
+
+/**
+ * Protocol handler for mcp:// URLs.
+ *
+ * URL form:
+ * - mcp://<resource-uri> (e.g. mcp://test://notes, mcp://ibkr://portfolio/positions)
+ */
+export class McpProtocolHandler implements ProtocolHandler {
+	readonly scheme = "mcp";
+
+	constructor(private readonly options: McpProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const mcpManager = this.options.getMcpManager();
+		if (!mcpManager) {
+			throw new Error("No MCP manager available. MCP servers may not be configured.");
+		}
+
+		const uri = extractResourceUri(url);
+		const targetServer = resolveTargetServer(mcpManager, uri);
+		if (!targetServer) {
+			throw new Error(
+				`No MCP server has resource "${uri}".\n\nAvailable resources:\n${formatAvailableResources(mcpManager)}`,
+			);
+		}
+
+		let result: MCPResourceReadResult | undefined;
+		try {
+			result = await mcpManager.readServerResource(targetServer, uri);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`MCP resource read error: ${message}`);
+		}
+
+		if (!result) {
+			throw new Error(`Server "${targetServer}" returned no content for "${uri}".`);
+		}
+
+		const textParts: string[] = [];
+		for (const item of result.contents) {
+			if (item.text !== undefined && item.text !== null) {
+				textParts.push(item.text);
+			} else if (item.blob) {
+				textParts.push(`[Binary content: ${item.mimeType ?? "unknown"}, base64 length ${item.blob.length}]`);
+			}
+		}
+
+		const content = textParts.length > 0 ? textParts.join("\n---\n") : "(empty resource)";
+		return {
+			url: url.href,
+			content,
+			contentType: "text/plain",
+			size: Buffer.byteLength(content, "utf-8"),
+			notes: [`MCP server: ${targetServer}`],
+		};
+	}
+}

package/src/internal-urls/memory-protocol.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@f5xc-salesdemos/pi-utils";
+import { validateRelativePath } from "./skill-protocol";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+const DEFAULT_MEMORY_FILE = "memory_summary.md";
+const MEMORY_NAMESPACE = "root";
+
+/**
+ * Options for the memory:// URL protocol.
+ */
+export interface MemoryProtocolOptions {
+	/**
+	 * Returns the absolute path to the current project's memory root.
+	 */
+	getMemoryRoot: () => string;
+}
+
+function ensureWithinRoot(targetPath: string, rootPath: string): void {
+	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
+		throw new Error("memory:// URL escapes memory root");
+	}
+}
+
+function toMemoryValidationError(error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(message.replace("skill://", "memory://"));
+}
+
+/**
+ * Resolve a memory:// URL to an absolute filesystem path under memory root.
+ */
+export function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): string {
+	const namespace = url.rawHost || url.hostname;
+	if (!namespace) {
+		throw new Error("memory:// URL requires a namespace: memory://root");
+	}
+	if (namespace !== MEMORY_NAMESPACE) {
+		throw new Error(`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE}`);
+	}
+
+	const rawPathname = url.rawPathname ?? url.pathname;
+	const hasPath = rawPathname && rawPathname !== "/" && rawPathname !== "";
+	if (!hasPath) {
+		return path.resolve(memoryRoot, DEFAULT_MEMORY_FILE);
+	}
+	let relativePath: string;
+	try {
+		relativePath = decodeURIComponent(rawPathname.slice(1));
+	} catch {
+		throw new Error(`Invalid URL encoding in memory:// path: ${url.href}`);
+	}
+
+	try {
+		validateRelativePath(relativePath);
+	} catch (error) {
+		throw toMemoryValidationError(error);
+	}
+
+	return path.resolve(memoryRoot, relativePath);
+}
+
+/**
+ * Protocol handler for memory:// URLs.
+ *
+ * URL forms:
+ * - memory://root - Reads memory_summary.md
+ * - memory://root/<path> - Reads a relative file under memory root
+ */
+export class MemoryProtocolHandler implements ProtocolHandler {
+	readonly scheme = "memory";
+
+	constructor(private readonly options: MemoryProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const memoryRoot = path.resolve(this.options.getMemoryRoot());
+		let resolvedRoot: string;
+		try {
+			resolvedRoot = await fs.realpath(memoryRoot);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(
+					"Memory artifacts are not available for this project yet. Run a session with memories enabled first.",
+				);
+			}
+			throw error;
+		}
+
+		const targetPath = resolveMemoryUrlToPath(url, resolvedRoot);
+		ensureWithinRoot(targetPath, resolvedRoot);
+
+		const parentDir = path.dirname(targetPath);
+		try {
+			const realParent = await fs.realpath(parentDir);
+			ensureWithinRoot(realParent, resolvedRoot);
+		} catch (error) {
+			if (!isEnoent(error)) {
+				throw error;
+			}
+		}
+
+		let realTargetPath: string;
+		try {
+			realTargetPath = await fs.realpath(targetPath);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(`Memory file not found: ${url.href}`);
+			}
+			throw error;
+		}
+
+		ensureWithinRoot(realTargetPath, resolvedRoot);
+
+		const stat = await fs.stat(realTargetPath);
+		if (!stat.isFile()) {
+			throw new Error(`memory:// URL must resolve to a file: ${url.href}`);
+		}
+
+		const content = await Bun.file(realTargetPath).text();
+		const ext = path.extname(realTargetPath).toLowerCase();
+		const contentType: InternalResource["contentType"] = ext === ".md" ? "text/markdown" : "text/plain";
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: realTargetPath,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/parse.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal URL parser that handles colons in the host segment.
+ *
+ * Standard `new URL()` interprets colons as port separators, which breaks
+ * namespaced internal URLs like `skill://plugin:name`. This parser extracts
+ * components via regex first, then falls back to a minimal URL-like object
+ * when `new URL()` fails.
+ *
+ * All code that parses internal URLs (router, protocol handlers, tools)
+ * MUST use this function instead of calling `new URL()` directly.
+ */
+import type { InternalUrl } from "./types";
+
+const SCHEME_HOST_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+const PATHNAME_RE = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/i;
+
+/**
+ * Parse an internal URL into an InternalUrl.
+ *
+ * Handles URLs where `new URL()` would fail (e.g., `skill://plugin:name`
+ * where the colon is not a port separator).
+ */
+export function parseInternalUrl(input: string): InternalUrl {
+	const hostMatch = input.match(SCHEME_HOST_RE);
+	const pathMatch = input.match(PATHNAME_RE);
+
+	let parsed: URL;
+	try {
+		parsed = new URL(input);
+	} catch {
+		// URL parse failed — build a minimal URL-like object from regex matches.
+		if (!hostMatch) {
+			throw new Error(`Invalid URL: ${input}`);
+		}
+		// Extract search and hash from the raw input before constructing the object.
+		const hashIdx = input.indexOf("#");
+		const hash = hashIdx !== -1 ? input.slice(hashIdx) : "";
+		const withoutHash = hashIdx !== -1 ? input.slice(0, hashIdx) : input;
+		const queryIdx = withoutHash.indexOf("?");
+		const search = queryIdx !== -1 ? withoutHash.slice(queryIdx) : "";
+		const queryString = search.slice(1); // strip leading ?
+
+		// Strip search/hash from pathname captured by regex.
+		let rawPathname = pathMatch?.[1] ?? "";
+		if (queryIdx !== -1 && rawPathname.includes("?")) {
+			rawPathname = rawPathname.slice(0, rawPathname.indexOf("?"));
+		}
+
+		parsed = {
+			protocol: `${hostMatch[1]}:`,
+			hostname: hostMatch[2] ?? "",
+			host: hostMatch[2] ?? "",
+			pathname: rawPathname,
+			href: input,
+			search,
+			hash,
+			searchParams: new URLSearchParams(queryString),
+		} as unknown as URL;
+	}
+
+	let rawHost = hostMatch ? hostMatch[2] : parsed.hostname;
+	try {
+		rawHost = decodeURIComponent(rawHost);
+	} catch {
+		// Leave rawHost as-is if decoding fails.
+	}
+
+	const result = parsed as InternalUrl;
+	result.rawHost = rawHost;
+	result.rawPathname = pathMatch?.[1] ?? parsed.pathname;
+	return result;
+}

package/src/internal-urls/profile-collectors.ts

@@ -0,0 +1,106 @@
+import { logger } from "@f5xc-salesdemos/pi-utils";
+import { $ } from "bun";
+
+import type { UserProfile } from "./user-profile";
+
+export interface ProfileCollector {
+	/** Unique identifier for this collector */
+	readonly id: string;
+	/** Human-readable name */
+	readonly name: string;
+	/** Fields this collector is the authoritative source for. Overwrites even pre-existing values. */
+	readonly authoritativeFields?: readonly string[];
+	/** Check if this collector can run (binary exists, platform ok, etc.) */
+	available(): Promise<boolean>;
+	/** Run the collector and return partial profile fields to merge */
+	collect(): Promise<Partial<UserProfile>>;
+}
+
+// ---------------------------------------------------------------------------
+// System (macOS)
+// ---------------------------------------------------------------------------
+
+async function detectDarwinLanguages(): Promise<string[]> {
+	const proc = await $`defaults read NSGlobalDomain AppleLanguages`.quiet().nothrow();
+	if (proc.exitCode !== 0) return [];
+
+	const raw = proc.stdout.toString().trim();
+	const inner = raw.replace(/^\(\s*/, "").replace(/\s*\)$/, "");
+	return inner
+		.split(",")
+		.map(s => s.trim().replace(/^"/, "").replace(/"$/, ""))
+		.filter(s => s.length > 0);
+}
+
+function detectLinuxLanguages(): string[] {
+	const languages: string[] = [];
+
+	// $LANGUAGE is a colon-separated priority list (e.g., "fr:de:en")
+	const langList = process.env.LANGUAGE;
+	if (langList) {
+		for (const l of langList.split(":")) {
+			const trimmed = l.trim();
+			if (trimmed) languages.push(trimmed);
+		}
+	}
+
+	// Fall back to $LANG (e.g., "fr_FR.UTF-8")
+	if (languages.length === 0) {
+		const lang = process.env.LANG;
+		if (lang) {
+			const code = lang.split(".")[0];
+			if (code && code !== "C" && code !== "POSIX") languages.push(code.replace(/_/g, "-"));
+		}
+	}
+
+	return languages;
+}
+
+const systemCollector: ProfileCollector = {
+	id: "system",
+	name: "System",
+
+	async available(): Promise<boolean> {
+		return process.platform === "darwin" || process.platform === "linux";
+	},
+
+	async collect(): Promise<Partial<UserProfile>> {
+		try {
+			const languages = process.platform === "darwin" ? await detectDarwinLanguages() : detectLinuxLanguages();
+
+			if (languages.length === 0) return {};
+			return { knowsLanguage: languages };
+		} catch (err: unknown) {
+			logger.debug("system collector failed", { error: err });
+			return {};
+		}
+	},
+};
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const _collectors: ProfileCollector[] = [systemCollector];
+
+export const PROFILE_COLLECTORS: readonly ProfileCollector[] = _collectors;
+
+export function registerProfileCollector(collector: ProfileCollector): void {
+	if (_collectors.some(c => c.id === collector.id)) {
+		logger.warn(`Profile collector '${collector.id}' already registered, skipping`);
+		return;
+	}
+	_collectors.push(collector);
+}
+
+export function unregisterProfileCollector(id: string): boolean {
+	const idx = _collectors.findIndex(c => c.id === id);
+	if (idx === -1) return false;
+	_collectors.splice(idx, 1);
+	return true;
+}
+
+export const collectorRegistry = {
+	register: registerProfileCollector,
+	unregister: unregisterProfileCollector,
+};

package/src/internal-urls/router.ts

@@ -0,0 +1,55 @@
+/**
+ * Internal URL router for internal protocols
+ * (agent://, artifact://, memory://, skill://, rule://, mcp://, xcsh://, local://, jobs://).
+ */
+import { parseInternalUrl } from "./parse";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+/**
+ * Router for internal URL schemes.
+ *
+ * Dispatches URLs like `agent://output_id` or `memory://root/memory_summary.md` to
+ * registered protocol handlers.
+ */
+export class InternalUrlRouter {
+	#handlers = new Map<string, ProtocolHandler>();
+
+	/**
+	 * Register a protocol handler.
+	 * @param handler Handler to register (uses handler.scheme as key)
+	 */
+	register(handler: ProtocolHandler): void {
+		this.#handlers.set(handler.scheme, handler);
+	}
+
+	/**
+	 * Check if the router can handle a URL.
+	 * @param input URL string to check
+	 */
+	canHandle(input: string): boolean {
+		const match = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+		if (!match) return false;
+		const scheme = match[1].toLowerCase();
+		return this.#handlers.has(scheme);
+	}
+
+	/**
+	 * Resolve an internal URL to its content.
+	 * @param input URL string (e.g., "agent://reviewer_0", "skill://notion-pages")
+	 * @throws Error if scheme is not registered or resolution fails
+	 */
+	async resolve(input: string): Promise<InternalResource> {
+		const parsed = parseInternalUrl(input);
+		const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+		const handler = this.#handlers.get(scheme);
+
+		if (!handler) {
+			const available = Array.from(this.#handlers.keys())
+				.map(s => `${s}://`)
+				.join(", ");
+			throw new Error(`Unknown protocol: ${scheme}://\nSupported: ${available || "none"}`);
+		}
+
+		return handler.resolve(parsed as InternalUrl);
+	}
+}

package/src/internal-urls/rule-protocol.ts

@@ -0,0 +1,55 @@
+/**
+ * Protocol handler for rule:// URLs.
+ *
+ * Resolves rule names to their content files.
+ *
+ * URL forms:
+ * - rule://<name> - Reads rule content
+ */
+import type { Rule } from "../capability/rule";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface RuleProtocolOptions {
+	/**
+	 * Returns the currently loaded rules.
+	 */
+	getRules: () => readonly Rule[];
+}
+
+/**
+ * Handler for rule:// URLs.
+ *
+ * Resolves rule names to their content.
+ */
+export class RuleProtocolHandler implements ProtocolHandler {
+	readonly scheme = "rule";
+
+	constructor(private readonly options: RuleProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const rules = this.options.getRules();
+
+		// Extract rule name from host
+		const ruleName = url.rawHost || url.hostname;
+		if (!ruleName) {
+			throw new Error("rule:// URL requires a rule name: rule://<name>");
+		}
+
+		// Find the rule
+		const rule = rules.find(r => r.name === ruleName);
+		if (!rule) {
+			const available = rules.map(r => r.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown rule: ${ruleName}\nAvailable: ${availableStr}`);
+		}
+
+		return {
+			url: url.href,
+			content: rule.content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(rule.content, "utf-8"),
+			sourcePath: rule.path,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/skill-protocol.ts

@@ -0,0 +1,111 @@
+/**
+ * Protocol handler for skill:// URLs.
+ *
+ * Resolves skill names to their SKILL.md files or relative paths within skill directories.
+ *
+ * URL forms:
+ * - skill://<name> - Reads SKILL.md
+ * - skill://<name>/<path> - Reads relative path within skill's baseDir
+ */
+import * as path from "node:path";
+import type { Skill } from "../extensibility/skills";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface SkillProtocolOptions {
+	/**
+	 * Returns the currently loaded skills.
+	 */
+	getSkills: () => readonly Skill[];
+}
+
+/**
+ * Get content type based on file extension.
+ */
+function getContentType(filePath: string): InternalResource["contentType"] {
+	const ext = path.extname(filePath).toLowerCase();
+	if (ext === ".md") return "text/markdown";
+	return "text/plain";
+}
+
+/**
+ * Validate that a path is safe (no traversal, no absolute paths).
+ */
+export function validateRelativePath(relativePath: string): void {
+	if (path.isAbsolute(relativePath)) {
+		throw new Error("Absolute paths are not allowed in skill:// URLs");
+	}
+
+	const normalized = path.normalize(relativePath);
+	if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("/..")) {
+		throw new Error("Path traversal (..) is not allowed in skill:// URLs");
+	}
+}
+
+/**
+ * Handler for skill:// URLs.
+ *
+ * Resolves skill names to their content files.
+ */
+export class SkillProtocolHandler implements ProtocolHandler {
+	readonly scheme = "skill";
+
+	constructor(private readonly options: SkillProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const skills = this.options.getSkills();
+
+		// Extract skill name from host
+		const skillName = url.rawHost || url.hostname;
+		if (!skillName) {
+			throw new Error("skill:// URL requires a skill name: skill://<name>");
+		}
+
+		// Find the skill
+		const skill = skills.find(s => s.name === skillName);
+		if (!skill) {
+			const available = skills.map(s => s.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown skill: ${skillName}\nAvailable: ${availableStr}`);
+		}
+
+		// Determine the file to read
+		let targetPath: string;
+		const urlPath = url.pathname;
+		const hasRelativePath = urlPath && urlPath !== "/" && urlPath !== "";
+
+		if (hasRelativePath) {
+			// Read relative path within skill's baseDir
+			const relativePath = decodeURIComponent(urlPath.slice(1)); // Remove leading /
+			validateRelativePath(relativePath);
+			targetPath = path.join(skill.baseDir, relativePath);
+
+			// Verify the resolved path is still within baseDir
+			const resolvedPath = path.resolve(targetPath);
+			const resolvedBaseDir = path.resolve(skill.baseDir);
+			if (!resolvedPath.startsWith(resolvedBaseDir + path.sep) && resolvedPath !== resolvedBaseDir) {
+				throw new Error("Path traversal is not allowed");
+			}
+		} else {
+			// Read SKILL.md
+			targetPath = skill.filePath;
+		}
+
+		// Read the file
+		const file = Bun.file(targetPath);
+		if (!(await file.exists())) {
+			throw new Error(`File not found: ${targetPath}`);
+		}
+
+		const content = await file.text();
+		const contentType = getContentType(targetPath);
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: targetPath,
+			notes: [],
+		};
+	}
+}