@f5-sales-demo/xcsh 19.68.0 → 19.70.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.68.0",
+	"version": "19.70.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.68.0",
-		"@f5-sales-demo/pi-agent-core": "19.68.0",
-		"@f5-sales-demo/pi-ai": "19.68.0",
-		"@f5-sales-demo/pi-natives": "19.68.0",
-		"@f5-sales-demo/pi-resource-management": "19.68.0",
-		"@f5-sales-demo/pi-tui": "19.68.0",
-		"@f5-sales-demo/pi-utils": "19.68.0",
+		"@f5-sales-demo/xcsh-stats": "19.70.0",
+		"@f5-sales-demo/pi-agent-core": "19.70.0",
+		"@f5-sales-demo/pi-ai": "19.70.0",
+		"@f5-sales-demo/pi-natives": "19.70.0",
+		"@f5-sales-demo/pi-resource-management": "19.70.0",
+		"@f5-sales-demo/pi-tui": "19.70.0",
+		"@f5-sales-demo/pi-utils": "19.70.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.68.0",
-	"commit": "84f5d14512c1e3c5afc1c2e21815c27c91e958e3",
-	"shortCommit": "84f5d14",
+	"version": "19.70.0",
+	"commit": "f3ee43f02bed815fe6236fa03883d3782d8a7969",
+	"shortCommit": "f3ee43f",
 	"branch": "main",
-	"tag": "v19.68.0",
-	"commitDate": "2026-07-21T12:18:05Z",
-	"buildDate": "2026-07-21T12:45:20.567Z",
+	"tag": "v19.70.0",
+	"commitDate": "2026-07-21T20:55:11Z",
+	"buildDate": "2026-07-21T21:16:15.358Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/84f5d14512c1e3c5afc1c2e21815c27c91e958e3",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.68.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/f3ee43f02bed815fe6236fa03883d3782d8a7969",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.70.0"
 };

package/src/internal-urls/index.ts

@@ -35,6 +35,7 @@ export * from "./local-protocol";
 export * from "./mcp-protocol";
 export * from "./memory-protocol";
 export * from "./parse";
+export * from "./plugin-resolve";
 export * from "./profile-collectors";
 export * from "./router";
 export * from "./rule-protocol";

package/src/internal-urls/plugin-resolve.test.ts

@@ -0,0 +1,86 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseInternalUrl } from "./parse";
+import { createPluginResolver, type PluginRootLike } from "./plugin-resolve";
+import type { InternalUrl } from "./types";
+
+let root: string;
+let roots: PluginRootLike[];
+
+function u(input: string): InternalUrl {
+	return parseInternalUrl(input) as InternalUrl;
+}
+
+beforeAll(async () => {
+	root = await fs.mkdtemp(path.join(os.tmpdir(), "plugin-resolve-"));
+	await fs.mkdir(path.join(root, ".xcsh-plugin"), { recursive: true });
+	await fs.mkdir(path.join(root, "schema"), { recursive: true });
+	await fs.mkdir(path.join(root, "engine"), { recursive: true });
+	await fs.writeFile(
+		path.join(root, ".xcsh-plugin", "resources.json"),
+		JSON.stringify({
+			schema: "schema/s.json",
+			engine: { runtime: "bun", entry: "engine/cli.ts", commands: ["validate"] },
+		}),
+	);
+	await fs.writeFile(path.join(root, "schema", "s.json"), `{"title":"x"}`);
+	await fs.writeFile(path.join(root, "engine", "cli.ts"), `console.log("hi")`);
+	// Symlink inside the plugin root pointing outside it (for escape-via-symlink test).
+	await fs.symlink(os.tmpdir(), path.join(root, "escape"));
+	roots = [{ plugin: "demo", version: "9.9.9", path: root }];
+});
+
+afterAll(async () => {
+	await fs.rm(root, { recursive: true, force: true });
+});
+
+describe("PluginResolver", () => {
+	const resolver = () => createPluginResolver(async () => roots);
+
+	test("schema returns application/json with a sourcePath inside the plugin root", async () => {
+		const r = await resolver().resolve(u("xcsh://plugin/demo/schema"));
+		expect(r.contentType).toBe("application/json");
+		expect(r.content).toContain(`"title"`);
+		expect(r.sourcePath).toBe(path.join(root, "schema", "s.json"));
+	});
+
+	test("contract returns the manifest verbatim with a sourcePath", async () => {
+		const r = await resolver().resolve(u("xcsh://plugin/demo/contract"));
+		expect(r.contentType).toBe("application/json");
+		expect(JSON.parse(r.content).schema).toBe("schema/s.json");
+		expect(r.sourcePath).toBe(path.join(root, ".xcsh-plugin", "resources.json"));
+	});
+
+	test("file/<relpath> resolves an arbitrary root-relative file", async () => {
+		const r = await resolver().resolve(u("xcsh://plugin/demo/file/engine/cli.ts"));
+		expect(r.sourcePath).toBe(path.join(root, "engine", "cli.ts"));
+		expect(r.content).toContain("hi");
+	});
+
+	test("engine returns the resolved entry path", async () => {
+		const r = await resolver().resolve(u("xcsh://plugin/demo/engine"));
+		const body = JSON.parse(r.content);
+		expect(body.entryPath).toBe(path.join(root, "engine", "cli.ts"));
+		expect(r.sourcePath).toBe(path.join(root, "engine", "cli.ts"));
+	});
+
+	test("uninstalled plugin throws listing installed names", async () => {
+		await expect(resolver().resolve(u("xcsh://plugin/nope/schema"))).rejects.toThrow(/not installed/i);
+	});
+
+	test("path traversal throws", async () => {
+		await expect(resolver().resolve(u("xcsh://plugin/demo/file/../../etc/hosts"))).rejects.toThrow(/traversal/i);
+	});
+
+	test("resolves purely from the injected getPluginRoots (no dependency on external flags)", async () => {
+		// Flag-independence at the sdk layer is guaranteed by listXcshPluginRoots not consulting enableXcshPlugins.
+		const r = await createPluginResolver(async () => roots).resolve(u("xcsh://plugin/demo"));
+		expect(JSON.parse(r.content).name).toBe("demo");
+	});
+
+	test("rejects escape via a symlink inside the plugin root", async () => {
+		await expect(resolver().resolve(u("xcsh://plugin/demo/file/escape/x"))).rejects.toThrow(/traversal/i);
+	});
+});

package/src/internal-urls/plugin-resolve.ts

@@ -0,0 +1,233 @@
+/**
+ * Generic resolver for xcsh://plugin/<name>/... URLs.
+ *
+ * Framework-agnostic: it reads a plugin-declared manifest
+ * (.xcsh-plugin/resources.json) and maps declared keys to files on disk. It has
+ * NO knowledge of any specific plugin's domain.
+ *
+ * URL forms (host = "plugin", first path segment = plugin name):
+ * - xcsh://plugin                       -> list installed plugins
+ * - xcsh://plugin/<name>                -> plugin summary (version, declared keys)
+ * - xcsh://plugin/<name>/contract       -> the manifest verbatim
+ * - xcsh://plugin/<name>/schema         -> file at manifest key "schema"
+ * - xcsh://plugin/<name>/engine         -> manifest engine block, entry resolved to abs path
+ * - xcsh://plugin/<name>/file/<relpath> -> any root-relative file
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { validateRelativePath } from "./skill-protocol";
+import type { InternalResource, InternalUrl } from "./types";
+
+/** Minimal shape the resolver needs from a discovered plugin root. */
+export interface PluginRootLike {
+	plugin: string;
+	version: string;
+	path: string;
+}
+
+export type GetPluginRoots = () => Promise<readonly PluginRootLike[]>;
+
+/** Manifest location, relative to a plugin root. */
+export const PLUGIN_MANIFEST_RELPATH = ".xcsh-plugin/resources.json";
+
+interface EngineBlock {
+	runtime?: string;
+	entry?: string;
+	commands?: string[];
+}
+
+interface ResourcesManifest {
+	engine?: EngineBlock;
+	[key: string]: unknown;
+}
+
+function contentTypeFor(filePath: string): InternalResource["contentType"] {
+	const ext = path.extname(filePath).toLowerCase();
+	if (ext === ".json") return "application/json";
+	if (ext === ".md") return "text/markdown";
+	return "text/plain";
+}
+
+/** realpath that tolerates a missing leaf by resolving the nearest existing ancestor. */
+async function realpathAllowingMissing(p: string): Promise<string> {
+	try {
+		return await fs.realpath(p);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+		const parent = path.dirname(p);
+		if (parent === p) throw err;
+		const realParent = await realpathAllowingMissing(parent);
+		return path.join(realParent, path.basename(p));
+	}
+}
+
+/** Join a root-relative path safely inside the plugin root; throws on traversal (incl. via symlink). */
+async function safeJoin(root: string, relativePath: string): Promise<string> {
+	try {
+		validateRelativePath(relativePath);
+	} catch {
+		// validateRelativePath's message names skill:// URLs; re-throw with the correct scheme.
+		throw new Error("Path traversal (..) or absolute paths are not allowed in xcsh://plugin/ URLs");
+	}
+	const lexicalTarget = path.resolve(path.join(root, relativePath));
+	const resolvedRoot = await fs.realpath(root);
+	const realTarget = await realpathAllowingMissing(path.join(resolvedRoot, relativePath));
+	if (realTarget !== resolvedRoot && !realTarget.startsWith(resolvedRoot + path.sep)) {
+		throw new Error("Path traversal is not allowed in xcsh://plugin/ URLs");
+	}
+	return lexicalTarget;
+}
+
+export class PluginResolver {
+	constructor(private readonly getPluginRoots: GetPluginRoots) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		// rawPathname preserves traversal markers; strip leading slash.
+		const rawPath = (url.rawPathname ?? url.pathname ?? "").replace(/^\/+/, "");
+		const segments = rawPath ? rawPath.split("/").map(s => decodeURIComponent(s)) : [];
+
+		const roots = await this.getPluginRoots();
+
+		// xcsh://plugin -> list installed plugins
+		if (segments.length === 0) {
+			return this.#json(url, await this.#listPlugins(roots));
+		}
+
+		const name = segments[0];
+		const root = roots.find(r => r.plugin === name);
+		if (!root) {
+			const installed = roots.map(r => r.plugin).join(", ") || "none";
+			throw new Error(`Plugin not installed: ${name}\nInstalled: ${installed}`);
+		}
+
+		const selector = segments.slice(1);
+
+		// xcsh://plugin/<name> -> summary
+		if (selector.length === 0) {
+			const manifest = await this.#readManifest(root.path);
+			return this.#json(url, {
+				name: root.plugin,
+				version: root.version,
+				resources: Object.keys(manifest),
+			});
+		}
+
+		const kind = selector[0];
+
+		if (kind === "contract") {
+			const manifestPath = path.join(root.path, PLUGIN_MANIFEST_RELPATH);
+			const content = await this.#readFile(manifestPath);
+			return {
+				url: url.href,
+				content,
+				contentType: "application/json",
+				size: Buffer.byteLength(content, "utf-8"),
+				sourcePath: manifestPath,
+				notes: [],
+			};
+		}
+
+		if (kind === "engine") {
+			const manifest = await this.#readManifest(root.path);
+			const engine = manifest.engine;
+			if (!engine?.entry) {
+				throw new Error(`Plugin ${name} declares no engine.entry in ${PLUGIN_MANIFEST_RELPATH}`);
+			}
+			const entryPath = await safeJoin(root.path, engine.entry);
+			await this.#assertExists(entryPath);
+			const body = JSON.stringify({
+				runtime: engine.runtime ?? null,
+				entry: engine.entry,
+				entryPath,
+				commands: engine.commands ?? [],
+			});
+			return {
+				url: url.href,
+				content: body,
+				contentType: "application/json",
+				size: Buffer.byteLength(body, "utf-8"),
+				sourcePath: entryPath,
+				notes: [],
+			};
+		}
+
+		if (kind === "file") {
+			const relativePath = selector.slice(1).join("/");
+			if (!relativePath) throw new Error("xcsh://plugin/<name>/file/ requires a relative path");
+			const target = await safeJoin(root.path, relativePath);
+			const content = await this.#readFile(target);
+			return {
+				url: url.href,
+				content,
+				contentType: contentTypeFor(target),
+				size: Buffer.byteLength(content, "utf-8"),
+				sourcePath: target,
+				notes: [],
+			};
+		}
+
+		// Named resource key from the manifest (e.g. "schema", "example").
+		const manifest = await this.#readManifest(root.path);
+		const value = manifest[kind];
+		if (typeof value !== "string") {
+			const keys = Object.keys(manifest).filter(k => typeof manifest[k] === "string");
+			throw new Error(`Unknown resource "${kind}" for plugin ${name}\nAvailable: ${keys.join(", ") || "none"}`);
+		}
+		const target = await safeJoin(root.path, value);
+		const content = await this.#readFile(target);
+		return {
+			url: url.href,
+			content,
+			contentType: contentTypeFor(target),
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: target,
+			notes: [],
+		};
+	}
+
+	async #listPlugins(
+		roots: readonly PluginRootLike[],
+	): Promise<Array<{ name: string; version: string; hasContract: boolean }>> {
+		const out: Array<{ name: string; version: string; hasContract: boolean }> = [];
+		for (const r of roots) {
+			const manifestPath = path.join(r.path, PLUGIN_MANIFEST_RELPATH);
+			const hasContract = await Bun.file(manifestPath).exists();
+			out.push({ name: r.plugin, version: r.version, hasContract });
+		}
+		return out;
+	}
+
+	async #readManifest(root: string): Promise<ResourcesManifest> {
+		const manifestPath = path.join(root, PLUGIN_MANIFEST_RELPATH);
+		const file = Bun.file(manifestPath);
+		if (!(await file.exists())) {
+			throw new Error(`Plugin manifest not found: ${manifestPath} (expected ${PLUGIN_MANIFEST_RELPATH})`);
+		}
+		return JSON.parse(await file.text()) as ResourcesManifest;
+	}
+
+	async #readFile(absPath: string): Promise<string> {
+		const file = Bun.file(absPath);
+		if (!(await file.exists())) throw new Error(`File not found: ${absPath}`);
+		return file.text();
+	}
+
+	async #assertExists(absPath: string): Promise<void> {
+		if (!(await Bun.file(absPath).exists())) throw new Error(`File not found: ${absPath}`);
+	}
+
+	#json(url: InternalUrl, data: unknown): InternalResource {
+		const content = JSON.stringify(data);
+		return {
+			url: url.href,
+			content,
+			contentType: "application/json",
+			size: Buffer.byteLength(content, "utf-8"),
+			notes: [],
+		};
+	}
+}
+
+export function createPluginResolver(getPluginRoots: GetPluginRoots): PluginResolver {
+	return new PluginResolver(getPluginRoots);
+}

package/src/internal-urls/xcsh-protocol.plugin.test.ts

@@ -0,0 +1,31 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseInternalUrl } from "./parse";
+import type { InternalUrl } from "./types";
+import { InternalDocsProtocolHandler } from "./xcsh-protocol";
+
+let root: string;
+
+beforeAll(async () => {
+	root = await fs.mkdtemp(path.join(os.tmpdir(), "xcsh-plugin-"));
+	await fs.mkdir(path.join(root, ".xcsh-plugin"), { recursive: true });
+	await fs.writeFile(path.join(root, ".xcsh-plugin", "resources.json"), JSON.stringify({ schema: "s.json" }));
+	await fs.writeFile(path.join(root, "s.json"), `{"ok":true}`);
+});
+afterAll(async () => {
+	await fs.rm(root, { recursive: true, force: true });
+});
+
+describe("InternalDocsProtocolHandler plugin host", () => {
+	const handler = new InternalDocsProtocolHandler({
+		getPluginRoots: async () => [{ plugin: "demo", version: "1.0.0", path: root }],
+	});
+
+	test("routes xcsh://plugin/<name>/schema", async () => {
+		const r = await handler.resolve(parseInternalUrl("xcsh://plugin/demo/schema") as InternalUrl);
+		expect(r.contentType).toBe("application/json");
+		expect(r.sourcePath).toBe(path.join(root, "s.json"));
+	});
+});

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

@@ -44,6 +44,7 @@ import { type ConsoleFieldMetadataData, EMPTY_CONSOLE_FIELD_METADATA } from "./c
 import { type ConsoleResolver, createConsoleResolver } from "./console-resolve";
 import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
 import extensionApiContent from "./extension-api.md" with { type: "text" };
+import { createPluginResolver, type GetPluginRoots, type PluginResolver } from "./plugin-resolve";
 import { createTerraformResolver, type TerraformResolver } from "./terraform-resolve";
 import type { TerraformIndex } from "./terraform-types";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
@@ -60,6 +61,7 @@ const USER_ROUTE = "user";
 const COMPUTER_ROUTE = "computer";
 const CONSOLE_HOST = "console";
 const EXTENSION_HOST = "extension";
+const PLUGIN_HOST = "plugin";
 const EMPTY_INDEX: ApiSpecIndex = { version: "unavailable", timestamp: "", domains: [] };
 const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
 	version: "unavailable",
@@ -265,6 +267,7 @@ export interface InternalDocsProtocolOptions {
 	readonly getContextStatus?: () => ContextStatus | null;
 	readonly apiSpecResolver?: ApiSpecResolver;
 	readonly apiCatalogResolver?: ApiCatalogResolver;
+	readonly getPluginRoots?: GetPluginRoots;
 }
 
 export class InternalDocsProtocolHandler implements ProtocolHandler {
@@ -275,6 +278,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#apiCatalogResolver: ApiCatalogResolver | null;
 	#terraformResolver: TerraformResolver | null;
 	#consoleResolver: ConsoleResolver | null = null;
+	#pluginResolver: PluginResolver | null = null;
+	readonly #getPluginRoots: GetPluginRoots | undefined;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
 		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
@@ -282,6 +287,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		this.#apiSpecResolver = options.apiSpecResolver ?? null;
 		this.#apiCatalogResolver = options.apiCatalogResolver ?? null;
 		this.#terraformResolver = null;
+		this.#getPluginRoots = options.getPluginRoots;
 	}
 
 	#getApiSpecResolver(): ApiSpecResolver {
@@ -325,6 +331,14 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		return this.#consoleResolver;
 	}
 
+	#getPluginResolver(): PluginResolver {
+		if (!this.#pluginResolver) {
+			const getRoots = this.#getPluginRoots ?? (async () => []);
+			this.#pluginResolver = createPluginResolver(getRoots);
+		}
+		return this.#pluginResolver;
+	}
+
 	async resolve(url: InternalUrl): Promise<InternalResource> {
 		const host = url.rawHost || url.hostname;
 
@@ -344,6 +358,10 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getTerraformResolver().resolve(url);
 		}
 
+		if (host === PLUGIN_HOST) {
+			return this.#getPluginResolver().resolve(url);
+		}
+
 		if (host === BRANDING_HOST) {
 			return this.#resolveBranding(url);
 		}

package/src/sdk.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import {
 	Agent,
 	type AgentEvent,
@@ -44,6 +45,7 @@ import { CursorExecHandlers } from "./cursor";
 import "./discovery";
 import { resolveConfigValue } from "./config/resolve-config-value";
 import { initializeWithSettings } from "./discovery";
+import { listXcshPluginRoots } from "./discovery/helpers";
 import { TtsrManager } from "./export/ttsr";
 import {
 	type CustomCommandsLoadResult,
@@ -1136,6 +1138,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						return null;
 					}
 				},
+				getPluginRoots: () => listXcshPluginRoots(os.homedir(), cwd).then(r => r.roots),
 			}),
 		);
 		internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));

package/src/tools/bash-skill-urls.ts

@@ -11,9 +11,9 @@ const SKILL_URL_PATTERN = /'skill:\/\/[^'\s")`\\]+'|"skill:\/\/[^"\s')`\\]+"|ski
 
 /** Regex to find supported internal URL tokens in command text. */
 const INTERNAL_URL_PATTERN =
-	/'(?:skill|agent|artifact|plan|memory|rule|local):\/\/[^'\s")`\\]+'|"(?:skill|agent|artifact|plan|memory|rule|local):\/\/[^"\s')`\\]+"|(?:skill|agent|artifact|plan|memory|rule|local):\/\/[^\s'")`\\]+/g;
+	/'(?:skill|agent|artifact|plan|memory|rule|local|xcsh):\/\/[^'\s")`\\]+'|"(?:skill|agent|artifact|plan|memory|rule|local|xcsh):\/\/[^"\s')`\\]+"|(?:skill|agent|artifact|plan|memory|rule|local|xcsh):\/\/[^\s'")`\\]+/g;
 
-const SUPPORTED_INTERNAL_SCHEMES = ["skill", "agent", "artifact", "plan", "memory", "rule", "local"] as const;
+const SUPPORTED_INTERNAL_SCHEMES = ["skill", "agent", "artifact", "plan", "memory", "rule", "local", "xcsh"] as const;
 
 type SupportedInternalScheme = (typeof SUPPORTED_INTERNAL_SCHEMES)[number];
 

package/src/tools/bash-skill-urls.xcsh.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import type { InternalResource } from "../internal-urls/types";
+import { expandInternalUrls } from "./bash-skill-urls";
+
+describe("expandInternalUrls xcsh scheme", () => {
+	const router = {
+		canHandle: (input: string) => input.startsWith("xcsh://"),
+		resolve: async (input: string): Promise<InternalResource> => ({
+			url: input,
+			content: "",
+			contentType: "application/json",
+			sourcePath: "/abs/plugin/engine/cli.ts",
+		}),
+	};
+
+	test("expands an xcsh:// token to a shell-escaped absolute path", async () => {
+		const out = await expandInternalUrls("bun xcsh://plugin/demo/file/engine/cli.ts score deal.json", {
+			skills: [],
+			internalRouter: router,
+		});
+		expect(out).toBe("bun '/abs/plugin/engine/cli.ts' score deal.json");
+	});
+
+	test("throws a friendly error when the resolved resource has no sourcePath", async () => {
+		const routerWithoutSourcePath = {
+			canHandle: (input: string) => input.startsWith("xcsh://"),
+			resolve: async (input: string): Promise<InternalResource> => ({
+				url: input,
+				content: "",
+				contentType: "application/json",
+				// list/summary endpoints (xcsh://plugin, xcsh://plugin/<name>) return no sourcePath
+			}),
+		};
+		await expect(
+			expandInternalUrls("bun xcsh://plugin/demo score x", {
+				skills: [],
+				internalRouter: routerWithoutSourcePath,
+			}),
+		).rejects.toThrow();
+	});
+});