@agimon-ai/po-help 0.0.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,732 @@
+import { DOOM_HELP_MAX_DIAGNOSTICS, DOOM_HELP_MAX_DIAGNOSTIC_LENGTH, DOOM_HELP_MAX_SKILLS } from "@agimon-ai/po-core/help";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { poHomeDirectory } from "@agimon-ai/po-core/piSettings";
+//#region src/services/llmsContent/index.ts
+const MAX_LLMS_BYTES = 1048576;
+const MARKDOWN_LINK_PATTERN = /!?\[[^\]]*\]\(\s*<?([^\s)>]+)>?(?:\s+[^)]*)?\)/gu;
+const MARKDOWN_REFERENCE_LINK_PATTERN = /^\s{0,3}\[[^\]\r\n]+\]:\s*<?([^\s>]+)>?/gmu;
+const MARKDOWN_AUTOLINK_PATTERN = /<((?:\.{0,2}\/|[A-Za-z][A-Za-z0-9+.-]*:)[^<>\s]+)>/gu;
+const HTML_LINK_PATTERN = /\b(?:href|src)\s*=\s*["']([^"']+)["']/giu;
+const URI_SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/iu;
+const NESTED_PATH_ENCODING_PATTERN = /%(?:25|2e|2f|3a|5c)/iu;
+const SAFE_EXTERNAL_SCHEMES = /* @__PURE__ */ new Set([
+	"http:",
+	"https:",
+	"mailto:"
+]);
+function externalScheme(target) {
+	if (!URI_SCHEME_PATTERN.test(target)) return void 0;
+	return target.slice(0, target.indexOf(":") + 1).toLowerCase();
+}
+function decodeRelativeTarget(rawTarget) {
+	let decoded = rawTarget;
+	try {
+		for (let pass = 0; pass < 2; pass += 1) {
+			const next = decodeURIComponent(decoded);
+			if (next === decoded) break;
+			decoded = next;
+		}
+	} catch {
+		throw new Error(`llms.txt contains an invalid encoded link '${rawTarget}'.`);
+	}
+	if (NESTED_PATH_ENCODING_PATTERN.test(decoded)) throw new Error(`llms.txt contains an unsafe nested encoding in link '${rawTarget}'.`);
+	return decoded;
+}
+function validateRelativeLink(rawTarget) {
+	if (!rawTarget || rawTarget.startsWith("#")) return;
+	const rawScheme = externalScheme(rawTarget);
+	if (rawScheme) {
+		if (!SAFE_EXTERNAL_SCHEMES.has(rawScheme)) throw new Error(`llms.txt contains unsupported link scheme '${rawScheme}'.`);
+		return;
+	}
+	const decoded = decodeRelativeTarget(rawTarget);
+	const decodedScheme = externalScheme(decoded);
+	if (decodedScheme) {
+		if (!SAFE_EXTERNAL_SCHEMES.has(decodedScheme)) throw new Error(`llms.txt contains unsupported link scheme '${decodedScheme}'.`);
+		return;
+	}
+	const withoutSuffix = decoded.split(/[?#]/u, 1)[0]?.replaceAll("\\", "/") ?? "";
+	if (withoutSuffix.startsWith("/") || withoutSuffix.split("/").some((segment) => segment === "..")) throw new Error(`llms.txt link '${rawTarget}' escapes the package root.`);
+}
+function containsUnsafeControl(text) {
+	for (const character of text) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code >= 0 && code <= 8 || code === 11 || code === 12 || code >= 14 && code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+function validateLlmsBytes(bytes) {
+	if (bytes.byteLength === 0) throw new Error("llms.txt is empty.");
+	if (bytes.byteLength > 1048576) throw new Error(`llms.txt exceeds ${MAX_LLMS_BYTES} bytes.`);
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new Error("llms.txt is not valid UTF-8.");
+	}
+	if (text.startsWith("")) text = text.slice(1);
+	if (containsUnsafeControl(text)) throw new Error("llms.txt contains unsafe control bytes.");
+	const firstContentLine = text.split(/\r?\n/u).find((line) => line.trim().length > 0)?.trim();
+	if (!firstContentLine || !/^#\s+\S/u.test(firstContentLine)) throw new Error("llms.txt must begin with a Markdown H1 heading.");
+	for (const pattern of [
+		MARKDOWN_LINK_PATTERN,
+		MARKDOWN_REFERENCE_LINK_PATTERN,
+		MARKDOWN_AUTOLINK_PATTERN,
+		HTML_LINK_PATTERN
+	]) for (const match of text.matchAll(pattern)) validateRelativeLink(match[1] ?? "");
+	return text;
+}
+function renderHelpSkillWrapper(descriptor, index) {
+	return `---\nname: ${JSON.stringify(descriptor.name)}\ndescription: ${JSON.stringify(descriptor.description)}\n---\n\n# Package Help\n\nRead the validated package Help index at ${JSON.stringify(index.filePath)}.\nResolve relative links in that index against ${JSON.stringify(index.referenceBase)}.\nOpen only the linked documents relevant to the current request, as needed; do not recursively load the whole reference set.\n`;
+}
+//#endregion
+//#region src/services/helpActivation/index.ts
+const MAX_RESOLUTION_CONCURRENCY = 4;
+const FAILURE_MESSAGE = "No package Help source could be activated.";
+const CANCELLATION_MESSAGE = "Help activation was cancelled.";
+var HelpActivationError = class extends Error {
+	constructor(message = FAILURE_MESSAGE) {
+		super(message);
+		this.name = "HelpActivationError";
+	}
+};
+function cloneContribution(contribution) {
+	return {
+		source: contribution.source,
+		moduleUrl: contribution.moduleUrl,
+		skills: contribution.skills.map((skill) => ({ ...skill }))
+	};
+}
+function cloneState(state) {
+	return {
+		activation: state.activation,
+		skills: state.skills.map((skill) => ({ ...skill })),
+		diagnostics: state.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+	};
+}
+function diagnostic(source, code, error) {
+	return {
+		source,
+		code,
+		message: ((error instanceof Error ? error.message : String(error)) || "Unknown Help activation failure.").slice(0, DOOM_HELP_MAX_DIAGNOSTIC_LENGTH)
+	};
+}
+function contributionFingerprint(contributions) {
+	return JSON.stringify(contributions.map((contribution) => ({
+		source: contribution.source,
+		moduleUrl: contribution.moduleUrl,
+		skills: contribution.skills
+	})));
+}
+var DefaultHelpActivationService = class {
+	dependencies;
+	listeners = /* @__PURE__ */ new Set();
+	contributions = [];
+	fingerprint = "[]";
+	state = {
+		activation: "inactive",
+		skills: [],
+		diagnostics: []
+	};
+	settledState = {
+		activation: "inactive",
+		skills: [],
+		diagnostics: []
+	};
+	generation = 0;
+	controller;
+	disposed = false;
+	constructor(dependencies) {
+		this.dependencies = dependencies;
+	}
+	getState() {
+		return cloneState(this.state);
+	}
+	replaceContributions(contributions) {
+		if (this.disposed) return;
+		const next = contributions.map(cloneContribution).sort((left, right) => left.source.localeCompare(right.source));
+		const fingerprint = contributionFingerprint(next);
+		if (fingerprint === this.fingerprint) return;
+		const previous = new Map(this.contributions.map((entry) => [entry.source, contributionFingerprint([entry])]));
+		const retained = new Set(next.filter((entry) => previous.get(entry.source) === contributionFingerprint([entry])).map((entry) => entry.source));
+		const skills = this.settledState.skills.filter((entry) => retained.has(entry.source));
+		const diagnostics = this.settledState.diagnostics.filter((entry) => !entry.source || retained.has(entry.source));
+		this.settledState = {
+			activation: skills.length === 0 ? "inactive" : diagnostics.length > 0 ? "degraded" : "active",
+			skills,
+			diagnostics
+		};
+		this.contributions = next;
+		this.fingerprint = fingerprint;
+		if (this.state.activation !== "inactive") this.activate().catch((error) => {
+			if (error instanceof HelpActivationError) return;
+			this.dependencies.onBackgroundError(error);
+		});
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	publish(state) {
+		this.state = cloneState(state);
+		if (state.activation !== "activating") this.settledState = cloneState(state);
+		this.dependencies.publisher.publish(this.state);
+		for (const listener of this.listeners) listener(cloneState(this.state));
+		return this.getState();
+	}
+	async loadSources(signal) {
+		const contributions = this.contributions;
+		const outcomes = Array.from({ length: contributions.length });
+		let cursor = 0;
+		const worker = async () => {
+			while (cursor < contributions.length) {
+				const index = cursor;
+				cursor += 1;
+				const contribution = contributions[index];
+				if (!contribution) return;
+				if (signal.aborted) throw new HelpActivationError(CANCELLATION_MESSAGE);
+				try {
+					const resolved = await this.dependencies.resolver.resolve(contribution, signal);
+					if (signal.aborted) throw new HelpActivationError(CANCELLATION_MESSAGE);
+					const skills = await this.dependencies.materializer.materialize(contribution, resolved, signal);
+					outcomes[index] = {
+						source: contribution.source,
+						loaded: {
+							contribution,
+							index: resolved,
+							skills
+						}
+					};
+				} catch (error) {
+					if (signal.aborted) throw new HelpActivationError(CANCELLATION_MESSAGE);
+					outcomes[index] = {
+						source: contribution.source,
+						error
+					};
+				}
+			}
+		};
+		const count = Math.min(MAX_RESOLUTION_CONCURRENCY, contributions.length);
+		await Promise.all(Array.from({ length: count }, () => worker()));
+		return outcomes;
+	}
+	async activate(externalSignal) {
+		if (this.disposed) throw new HelpActivationError("Help runtime is disposed.");
+		this.controller?.abort("Help activation generation replaced.");
+		const controller = new AbortController();
+		this.controller = controller;
+		const generation = ++this.generation;
+		const abortFromExternal = () => controller.abort(externalSignal?.reason);
+		externalSignal?.addEventListener("abort", abortFromExternal, { once: true });
+		if (externalSignal?.aborted) abortFromExternal();
+		const settledState = cloneState(this.settledState);
+		this.publish({
+			activation: "activating",
+			skills: settledState.skills,
+			diagnostics: settledState.diagnostics
+		});
+		try {
+			const outcomes = await this.loadSources(controller.signal);
+			if (controller.signal.aborted || generation !== this.generation) throw new HelpActivationError(CANCELLATION_MESSAGE);
+			const diagnostics = [];
+			const loaded = [];
+			let aggregateBytes = 0;
+			for (const outcome of outcomes) {
+				if (!outcome) continue;
+				if (outcome.error || !outcome.loaded) {
+					diagnostics.push(diagnostic(outcome.source, "HELP_SOURCE_FAILED", outcome.error));
+					continue;
+				}
+				if (aggregateBytes + outcome.loaded.index.byteLength > 4194304) {
+					diagnostics.push(diagnostic(outcome.source, "HELP_AGGREGATE_LIMIT", "The aggregate llms.txt byte limit was exceeded."));
+					continue;
+				}
+				aggregateBytes += outcome.loaded.index.byteLength;
+				loaded.push(outcome.loaded);
+			}
+			const skills = [];
+			const names = /* @__PURE__ */ new Set();
+			for (const source of loaded) for (const skill of source.skills) {
+				if (skills.length >= DOOM_HELP_MAX_SKILLS) {
+					diagnostics.push(diagnostic(source.contribution.source, "HELP_SKILL_LIMIT", "The Help skill limit was reached."));
+					break;
+				}
+				if (names.has(skill.name)) {
+					diagnostics.push(diagnostic(source.contribution.source, "HELP_SKILL_COLLISION", `Help skill '${skill.name}' was already provided by an earlier package source.`));
+					continue;
+				}
+				names.add(skill.name);
+				skills.push({ ...skill });
+			}
+			const boundedDiagnostics = diagnostics.slice(0, DOOM_HELP_MAX_DIAGNOSTICS);
+			if (skills.length === 0) {
+				this.publish({
+					activation: "inactive",
+					skills: [],
+					diagnostics: boundedDiagnostics
+				});
+				throw new HelpActivationError();
+			}
+			return this.publish({
+				activation: boundedDiagnostics.length > 0 ? "degraded" : "active",
+				skills,
+				diagnostics: boundedDiagnostics
+			});
+		} catch (error) {
+			if (generation === this.generation && this.state.activation === "activating") this.publish(settledState);
+			throw error;
+		} finally {
+			externalSignal?.removeEventListener("abort", abortFromExternal);
+			if (this.controller === controller) this.controller = void 0;
+		}
+	}
+	deactivate() {
+		this.generation += 1;
+		this.controller?.abort("Help deactivated.");
+		this.controller = void 0;
+		return this.publish({
+			activation: "inactive",
+			skills: [],
+			diagnostics: []
+		});
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.deactivate();
+		this.disposed = true;
+		this.listeners.clear();
+	}
+};
+//#endregion
+//#region src/services/helpStorage/index.ts
+const PACKAGE_MANIFEST = "package.json";
+const HELP_INDEX_PATH$1 = "llms.txt";
+const CACHE_SCHEMA_VERSION = 1;
+const PRIVATE_FILE_MODE = 384;
+const PRIVATE_DIRECTORY_MODE = 448;
+const COMPLETION_FILE = ".complete";
+const CACHE_METADATA_FILE = "metadata.json";
+const WRAPPER_DIRECTORY = "wrappers";
+const SKILL_FILE = "SKILL.md";
+const EXACT_SEMVER_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+function assertNotAborted(signal) {
+	if (signal.aborted) throw new Error("Help activation was cancelled.");
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isContained(root, candidate) {
+	const relative = path.relative(root, candidate);
+	return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function readManifest(filePath) {
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+	} catch (error) {
+		throw new Error(`Cannot read Help package manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!isRecord$1(parsed)) throw new Error(`Help package manifest at ${filePath} must contain an object.`);
+	return parsed;
+}
+function resolveHelpPackageIdentity(moduleUrl, expectedSource) {
+	if (!NPM_PACKAGE_NAME_PATTERN.test(expectedSource)) throw new Error(`Help source '${expectedSource}' must be a valid lowercase npm package name.`);
+	let modulePath;
+	try {
+		const url = new URL(moduleUrl);
+		if (url.protocol !== "file:") throw new Error(`Help module URL must use file:, received ${url.protocol}`);
+		modulePath = fs.realpathSync(fileURLToPath(url));
+	} catch (error) {
+		throw new Error(`Invalid Help contributor module URL '${moduleUrl}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!fs.lstatSync(modulePath).isFile()) throw new Error(`Help contributor module is not a regular file: ${modulePath}`);
+	let directory = path.dirname(modulePath);
+	while (true) {
+		const manifestPath = path.join(directory, PACKAGE_MANIFEST);
+		if (fs.existsSync(manifestPath)) {
+			const manifest = readManifest(manifestPath);
+			const source = manifest.name;
+			const version = manifest.version;
+			if (source !== expectedSource) throw new Error(`Help source '${expectedSource}' does not match nearest package '${String(source)}'.`);
+			if (typeof version !== "string" || !EXACT_SEMVER_PATTERN.test(version)) throw new Error(`Help package '${expectedSource}' must declare an exact semantic version.`);
+			const packageRoot = fs.realpathSync(directory);
+			if (!isContained(packageRoot, modulePath)) throw new Error("Help contributor module escapes its resolved package root.");
+			return {
+				source: expectedSource,
+				version,
+				packageRoot,
+				modulePath
+			};
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
+	}
+	throw new Error(`Cannot find a package manifest for Help contributor ${modulePath}.`);
+}
+function defaultHelpCacheRoot(homeDirectory = os.homedir()) {
+	return path.join(poHomeDirectory(homeDirectory), "llms-cache");
+}
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+function parseCacheMetadata(value, identity) {
+	if (!isRecord$1(value)) return void 0;
+	if (value.schemaVersion !== CACHE_SCHEMA_VERSION || value.source !== identity.source || value.version !== identity.version || value.path !== HELP_INDEX_PATH$1 || typeof value.integrity !== "string" || typeof value.digest !== "string" || typeof value.referenceBase !== "string") return;
+	return value;
+}
+function regularFile(filePath) {
+	try {
+		const metadata = fs.lstatSync(filePath);
+		return metadata.isFile() && !metadata.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+var HelpIndexCache = class {
+	root;
+	constructor(root = defaultHelpCacheRoot()) {
+		this.root = root;
+	}
+	entryDirectory(identity) {
+		const key = sha256Hex(`${identity.source}\0${identity.version}\0${HELP_INDEX_PATH$1}`);
+		return path.join(this.root, key);
+	}
+	discard(identity) {
+		fs.rmSync(this.entryDirectory(identity), {
+			recursive: true,
+			force: true
+		});
+	}
+	read(identity) {
+		const directory = this.entryDirectory(identity);
+		const completionPath = path.join(directory, COMPLETION_FILE);
+		const indexPath = path.join(directory, HELP_INDEX_PATH$1);
+		const metadataPath = path.join(directory, CACHE_METADATA_FILE);
+		if (!regularFile(completionPath) || !regularFile(indexPath) || !regularFile(metadataPath)) return void 0;
+		try {
+			const metadata = parseCacheMetadata(JSON.parse(fs.readFileSync(metadataPath, "utf8")), identity);
+			if (!metadata) return void 0;
+			const bytes = fs.readFileSync(indexPath);
+			if (sha256Hex(bytes) !== metadata.digest) return void 0;
+			if (fs.readFileSync(completionPath, "utf8").trim() !== metadata.digest) return void 0;
+			return {
+				bytes,
+				filePath: indexPath,
+				integrity: metadata.integrity,
+				digest: metadata.digest,
+				referenceBase: metadata.referenceBase
+			};
+		} catch {
+			return;
+		}
+	}
+	publish(identity, bytes, integrity, referenceBase, signal) {
+		assertNotAborted(signal);
+		const existing = this.read(identity);
+		if (existing) return existing;
+		const directory = this.entryDirectory(identity);
+		fs.mkdirSync(this.root, {
+			mode: PRIVATE_DIRECTORY_MODE,
+			recursive: true
+		});
+		if (fs.existsSync(directory)) fs.rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+		const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;
+		const digest = sha256Hex(bytes);
+		const metadata = {
+			schemaVersion: CACHE_SCHEMA_VERSION,
+			source: identity.source,
+			version: identity.version,
+			path: HELP_INDEX_PATH$1,
+			integrity,
+			digest,
+			referenceBase
+		};
+		try {
+			fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });
+			fs.writeFileSync(path.join(temporary, HELP_INDEX_PATH$1), bytes, { mode: PRIVATE_FILE_MODE });
+			fs.writeFileSync(path.join(temporary, CACHE_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: PRIVATE_FILE_MODE });
+			assertNotAborted(signal);
+			fs.writeFileSync(path.join(temporary, COMPLETION_FILE), `${digest}\n`, { mode: PRIVATE_FILE_MODE });
+			try {
+				fs.renameSync(temporary, directory);
+			} catch (error) {
+				const winner = this.read(identity);
+				if (winner) return winner;
+				throw error;
+			}
+			return {
+				bytes: Uint8Array.from(bytes),
+				filePath: path.join(directory, HELP_INDEX_PATH$1),
+				integrity,
+				digest,
+				referenceBase
+			};
+		} finally {
+			fs.rmSync(temporary, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+var DefaultHelpSkillMaterializer = class {
+	cacheRoot;
+	constructor(cacheRoot = defaultHelpCacheRoot()) {
+		this.cacheRoot = cacheRoot;
+	}
+	async materialize(contribution, index, signal) {
+		const skills = [];
+		for (const descriptor of contribution.skills) {
+			assertNotAborted(signal);
+			const key = sha256Hex(`${index.identity.source}\0${index.identity.version}\0${descriptor.name}\0${descriptor.description}\0${index.digest}`);
+			const directory = path.join(this.cacheRoot, WRAPPER_DIRECTORY, key);
+			const filePath = path.join(directory, SKILL_FILE);
+			const content = renderHelpSkillWrapper(descriptor, index);
+			if (!regularFile(filePath) || fs.readFileSync(filePath, "utf8") !== content) {
+				fs.mkdirSync(path.dirname(directory), {
+					mode: PRIVATE_DIRECTORY_MODE,
+					recursive: true
+				});
+				if (fs.existsSync(directory)) fs.rmSync(directory, {
+					recursive: true,
+					force: true
+				});
+				const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;
+				try {
+					fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });
+					fs.writeFileSync(path.join(temporary, SKILL_FILE), content, { mode: PRIVATE_FILE_MODE });
+					assertNotAborted(signal);
+					try {
+						fs.renameSync(temporary, directory);
+					} catch (error) {
+						if (!regularFile(filePath) || fs.readFileSync(filePath, "utf8") !== content) throw error;
+					}
+				} finally {
+					fs.rmSync(temporary, {
+						recursive: true,
+						force: true
+					});
+				}
+			}
+			skills.push({
+				source: contribution.source,
+				name: descriptor.name,
+				description: descriptor.description,
+				filePath,
+				baseDir: directory
+			});
+		}
+		return skills;
+	}
+};
+//#endregion
+//#region src/services/llmsResolver/index.ts
+const HELP_INDEX_PATH = "llms.txt";
+const UNPKG_ORIGIN = "https://unpkg.com";
+const DEFAULT_FETCH_TIMEOUT_MS = 5e3;
+const MAX_METADATA_BYTES = 524288;
+const MAX_REDIRECTS = 3;
+const SRI_PATTERN = /^sha256-([A-Za-z0-9+/]+={0,2})$/u;
+function defaultFetch(input, init) {
+	return fetch(input, init);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRegularFile(filePath) {
+	try {
+		const metadata = fs.lstatSync(filePath);
+		return metadata.isFile() && !metadata.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+function unpkgPackagePath(source, version) {
+	return `${source.split("/").map((segment) => segment.startsWith("@") ? `@${encodeURIComponent(segment.slice(1))}` : encodeURIComponent(segment)).join("/")}@${encodeURIComponent(version)}`;
+}
+function exactUnpkgBase(source, version) {
+	return `${UNPKG_ORIGIN}/${unpkgPackagePath(source, version)}/`;
+}
+function contentLength(response) {
+	const raw = response.headers.get("content-length");
+	if (!raw) return void 0;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
+}
+function timeoutSignal(parent, timeoutMs) {
+	const controller = new AbortController();
+	const abort = () => controller.abort(parent.reason);
+	parent.addEventListener("abort", abort, { once: true });
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Help download timed out.")), timeoutMs);
+	if (parent.aborted) abort();
+	return {
+		signal: controller.signal,
+		dispose() {
+			clearTimeout(timer);
+			parent.removeEventListener("abort", abort);
+		}
+	};
+}
+async function fetchExact(fetcher, initialUrl, signal) {
+	let url = initialUrl;
+	const expected = new URL(initialUrl);
+	for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
+		const response = await fetcher(url, {
+			signal,
+			redirect: "manual"
+		});
+		if (response.status < 300 || response.status >= 400) return response;
+		const location = response.headers.get("location");
+		if (!location) throw new Error(`Unpkg redirected ${url} without a location.`);
+		const next = new URL(location, url);
+		if (next.origin !== UNPKG_ORIGIN || next.pathname !== expected.pathname || next.search !== expected.search) throw new Error(`Unpkg redirect escaped the exact package/version path: ${next.href}`);
+		url = next.href;
+	}
+	throw new Error(`Unpkg exceeded ${MAX_REDIRECTS} redirects.`);
+}
+function parseMetadata(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new Error("Unpkg metadata is not valid JSON.");
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed.files)) throw new Error("Unpkg metadata has no files list.");
+	const match = parsed.files.find((entry) => isRecord(entry) && entry.path === `/${HELP_INDEX_PATH}`);
+	if (!isRecord(match) || typeof match.integrity !== "string") throw new Error(`Unpkg package does not publish /${HELP_INDEX_PATH}.`);
+	const size = typeof match.size === "number" ? match.size : void 0;
+	if (size !== void 0 && (!Number.isSafeInteger(size) || size < 0 || size > 1048576)) throw new Error(`Unpkg /${HELP_INDEX_PATH} exceeds the Help size limit.`);
+	if (!SRI_PATTERN.test(match.integrity)) throw new Error("Unpkg llms.txt metadata does not contain SHA-256 SRI.");
+	return {
+		path: match.path,
+		...size === void 0 ? {} : { size },
+		integrity: match.integrity
+	};
+}
+function verifySri(bytes, integrity) {
+	const expected = SRI_PATTERN.exec(integrity)?.[1];
+	if (!expected) throw new Error("Invalid llms.txt SRI metadata.");
+	if (createHash("sha256").update(bytes).digest("base64") !== expected) throw new Error("Downloaded llms.txt failed SRI verification.");
+}
+var DefaultHelpIndexResolver = class {
+	cache;
+	fetcher;
+	timeoutMs;
+	constructor(options = {}) {
+		this.cache = options.cache ?? new HelpIndexCache();
+		this.fetcher = options.fetch ?? defaultFetch;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+	}
+	async resolve(contribution, signal) {
+		if (signal.aborted) throw new Error("Help activation was cancelled.");
+		const identity = resolveHelpPackageIdentity(contribution.moduleUrl, contribution.source);
+		const localPath = path.join(identity.packageRoot, HELP_INDEX_PATH);
+		if (fs.existsSync(localPath)) {
+			if (!isRegularFile(localPath)) throw new Error(`Bundled ${HELP_INDEX_PATH} must be a regular file.`);
+			const bytes = fs.readFileSync(localPath);
+			validateLlmsBytes(bytes);
+			return {
+				identity,
+				location: "local",
+				filePath: localPath,
+				referenceBase: identity.packageRoot,
+				byteLength: bytes.byteLength,
+				digest: sha256Hex(bytes)
+			};
+		}
+		const cached = this.cache.read(identity);
+		if (cached) try {
+			validateLlmsBytes(cached.bytes);
+			return {
+				identity,
+				location: "cache",
+				filePath: cached.filePath,
+				referenceBase: cached.referenceBase,
+				byteLength: cached.bytes.byteLength,
+				digest: cached.digest
+			};
+		} catch {
+			this.cache.discard(identity);
+		}
+		const timed = timeoutSignal(signal, this.timeoutMs);
+		try {
+			const referenceBase = exactUnpkgBase(identity.source, identity.version);
+			const metadataResponse = await fetchExact(this.fetcher, `${referenceBase}?meta`, timed.signal);
+			const metadataLength = contentLength(metadataResponse);
+			if (metadataLength !== void 0 && metadataLength > MAX_METADATA_BYTES) throw new Error("Unpkg metadata exceeds the Help metadata size limit.");
+			if (!metadataResponse.ok) throw new Error(`Unpkg metadata request failed with HTTP ${metadataResponse.status}.`);
+			const metadataText = await metadataResponse.text();
+			if (Buffer.byteLength(metadataText, "utf8") > MAX_METADATA_BYTES) throw new Error("Unpkg metadata exceeds the Help metadata size limit.");
+			const metadata = parseMetadata(metadataText);
+			const indexResponse = await fetchExact(this.fetcher, `${referenceBase}${HELP_INDEX_PATH}`, timed.signal);
+			const indexLength = contentLength(indexResponse);
+			if (indexLength !== void 0 && indexLength > 1048576) throw new Error(`Downloaded ${HELP_INDEX_PATH} exceeds ${MAX_LLMS_BYTES} bytes.`);
+			if (!indexResponse.ok) throw new Error(`Unpkg llms.txt request failed with HTTP ${indexResponse.status}.`);
+			const bytes = new Uint8Array(await indexResponse.arrayBuffer());
+			validateLlmsBytes(bytes);
+			verifySri(bytes, metadata.integrity);
+			const published = this.cache.publish(identity, bytes, metadata.integrity, referenceBase, timed.signal);
+			return {
+				identity,
+				location: "remote",
+				filePath: published.filePath,
+				referenceBase: published.referenceBase,
+				byteLength: published.bytes.byteLength,
+				digest: published.digest
+			};
+		} finally {
+			timed.dispose();
+		}
+	}
+};
+//#endregion
+//#region src/services/helpRuntime/index.ts
+function reportAsync(error) {
+	queueMicrotask(() => {
+		throw error instanceof Error ? error : new Error(String(error));
+	});
+}
+function createHelpRuntime(service, options = {}) {
+	const cacheRoot = options.cacheRoot ?? defaultHelpCacheRoot();
+	const activation = new DefaultHelpActivationService({
+		resolver: new DefaultHelpIndexResolver({
+			cache: new HelpIndexCache(cacheRoot),
+			fetch: options.fetch,
+			timeoutMs: options.timeoutMs
+		}),
+		materializer: new DefaultHelpSkillMaterializer(cacheRoot),
+		publisher: { publish: (snapshot) => service.publish(snapshot) },
+		onBackgroundError(error) {
+			if (options.onBackgroundError) options.onBackgroundError(error);
+			else reportAsync(error);
+		}
+	});
+	const synchronize = (contributions) => {
+		activation.replaceContributions(contributions);
+	};
+	const unsubscribe = service.subscribeContributions((contributions) => synchronize(contributions));
+	synchronize(service.listContributions());
+	let disposed = false;
+	return {
+		activation,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			unsubscribe();
+			activation.dispose();
+		}
+	};
+}
+//#endregion
+export { DefaultHelpActivationService, DefaultHelpIndexResolver, DefaultHelpSkillMaterializer, HelpIndexCache, createHelpRuntime, defaultHelpCacheRoot };
+
+//# sourceMappingURL=index.mjs.map