@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/providers/types/runtime-descriptor.ts

@@ -0,0 +1,170 @@
+import type { Api, Model } from "../../../engine/types.js";
+
+import type { CapabilityFlags } from "./capability-flags.js";
+import type { CompleteOptions, CompletionChunk, EmbedResult, InfillOptions, RerankResult } from "./inference.js";
+import type { KnowledgeBaseHit } from "./knowledge-base.js";
+import type { TargetDescriptor } from "./target-descriptor.js";
+
+export type RuntimeKind = "http" | "sdk" | "subprocess";
+export type RuntimeTier = "protocol" | "cloud" | "local-native" | "subscription";
+
+export type RuntimeApiFamily =
+	| "openai-completions"
+	| "openai-responses"
+	| "openai-codex-responses"
+	| "azure-openai-responses"
+	| "anthropic-messages"
+	| "bedrock-converse-stream"
+	| "google-generative-ai"
+	| "google-vertex"
+	| "lmstudio-native"
+	| "mistral-conversations"
+	| "ollama-native"
+	| "rerank-http"
+	| "embeddings-http"
+	| "claude-agent-sdk"
+	| "claude-code-subprocess";
+
+export type RuntimeAuth = "api-key" | "oauth" | "aws-sdk" | "vertex-adc" | "claude-cli" | "none";
+
+export interface ProbeContext {
+	credentialsPresent: ReadonlySet<string>;
+	httpTimeoutMs: number;
+	signal?: AbortSignal;
+	/**
+	 * Resolved bearer/API token for the target being probed, when one is
+	 * available from stored auth, environment, or refreshed OAuth credentials.
+	 * Auth-gated discovery endpoints can use this instead of reaching into auth
+	 * storage directly.
+	 */
+	authToken?: string;
+}
+
+/**
+ * Map of which inference surfaces a probe found at the target.
+ * Composite local descriptors (llamacpp, lemonade) populate this from a
+ * batched HEAD/GET sweep; fields are absent when the surface did not respond.
+ * Values are the path the probe used so callers can cite it in errors.
+ */
+export interface ProbeSurfaceMap {
+	anthropicMessages?: string;
+	openaiChat?: string;
+	embeddings?: string;
+	rerank?: string;
+	completion?: string;
+	infill?: string;
+}
+
+export type ProbeModelLoadState = "loaded" | "loading" | "unloaded" | "failed" | "unknown";
+
+export interface ProbeModelStatus {
+	state: ProbeModelLoadState;
+	detail?: string;
+	/**
+	 * Context the runtime has this model loaded at, when it reports one. LM
+	 * Studio serves a loaded instance at whatever window it was opened with,
+	 * which is routinely well below the model's `max_context_length`, and that
+	 * smaller number is the one a run has to be planned against. Absent when the
+	 * model is not resident or the runtime does not report it.
+	 */
+	contextLength?: number;
+	/**
+	 * Resident footprint reported by the runtime when a model is loaded. Ollama
+	 * exposes both via `/api/ps` (`size_vram` is the GPU-resident portion,
+	 * `size` the total). Captured here so the picker and any future VRAM-fit
+	 * hinting have a real number to work with instead of re-probing.
+	 */
+	sizeVramBytes?: number;
+	sizeBytes?: number;
+}
+
+export interface ProbeResult {
+	ok: boolean;
+	latencyMs?: number;
+	error?: string;
+	serverVersion?: string;
+	models?: string[];
+	/** Probe-only per-model load state when the runtime exposes it. */
+	modelStates?: Record<string, ProbeModelStatus>;
+	discoveredCapabilities?: Partial<CapabilityFlags>;
+	/** Probe-only capabilities keyed by wire model id when a runtime can list model metadata. */
+	modelCapabilities?: Record<string, Partial<CapabilityFlags>>;
+	/** Wire model id those discovered capabilities describe, when known. */
+	capabilityModelId?: string;
+	/**
+	 * Free-form diagnostic notes from the probe. llama.cpp uses this to flag a
+	 * mismatch between the configured wire model id and the server's loaded
+	 * weights (single-model server, so there is no eviction recourse).
+	 */
+	notes?: ReadonlyArray<string>;
+	/**
+	 * Composite descriptors set this to the api family they will use for chat.
+	 * `synthesizeModel` reads it back out of the cached probe state to choose
+	 * which provider implementation pi-ai routes to. Absent when the descriptor
+	 * is single-surface or no chat surface was reachable.
+	 */
+	chatApiFamily?: RuntimeApiFamily;
+	surfaces?: ProbeSurfaceMap;
+}
+
+export interface ReasoningProbeResult {
+	reasoning: boolean;
+	latencyMs: number;
+	error?: string;
+}
+
+export interface RuntimeDescriptor {
+	id: string;
+	displayName: string;
+	kind: RuntimeKind;
+	tier?: RuntimeTier;
+	apiFamily: RuntimeApiFamily;
+	auth: RuntimeAuth;
+	credentialsEnvVar?: string;
+	/**
+	 * pi-ai OAuth provider id backing this runtime when `auth === "oauth"` and it
+	 * differs from `id`. `openai-codex` omits this because its registry id, target
+	 * `oauthProfile`, and pi-ai provider id all coincide. The Claude Pro/Max
+	 * runtime sets this to `"anthropic"` so login/refresh/credential storage key
+	 * on the pi-ai `anthropic` OAuth provider while keeping a distinct registry id
+	 * (`anthropic-max`) from the api-key `anthropic` runtime.
+	 */
+	oauthProviderId?: string;
+	/**
+	 * Optional one-line notice printed before an interactive `clio-coder auth login` or
+	 * configure connect for this runtime. Used to surface subscription usage-terms
+	 * considerations so OAuth subscription paths are an explicit, informed opt-in.
+	 */
+	authNotice?: string;
+	knownModels?: string[];
+	binaryName?: string;
+	defaultBinaryPath?: string;
+	headlessCommand?: string;
+	outputParser?: string;
+	defaultCapabilities: CapabilityFlags;
+	/**
+	 * When true, this id is a real, distinct runtime (e.g. `llamacpp-anthropic`,
+	 * the Anthropic Messages surface on llama.cpp, or the embed/rerank runtimes)
+	 * that stays resolvable by id but is hidden from `clio-coder configure --list` and
+	 * the interactive wizard, where a composite descriptor owns the
+	 * user-visible slot.
+	 */
+	hidden?: boolean;
+	probe?(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult>;
+	probeModels?(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]>;
+	/**
+	 * Optional per-model reasoning capability probe. Protocol-compatible local
+	 * servers (LM Studio, llama.cpp, Ollama, ...) advertise an OpenAI or
+	 * Anthropic wire surface regardless of whether the loaded model supports
+	 * thinking. Implementations here send a one-shot priming request and look at
+	 * `reasoning_content` / `reasoning` / `reasoning_text` in the response.
+	 * Result is cached per (target, model) by the providers domain so
+	 * /thinking can surface the correct level set.
+	 */
+	probeReasoning?(target: TargetDescriptor, modelId: string, ctx: ProbeContext): Promise<ReasoningProbeResult>;
+	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api>;
+	complete?(target: TargetDescriptor, opts: CompleteOptions, ctx: ProbeContext): AsyncIterable<CompletionChunk>;
+	infill?(target: TargetDescriptor, opts: InfillOptions, ctx: ProbeContext): AsyncIterable<CompletionChunk>;
+	embed?(target: TargetDescriptor, input: string | string[], ctx: ProbeContext): Promise<EmbedResult>;
+	rerank?(target: TargetDescriptor, query: string, documents: string[], ctx: ProbeContext): Promise<RerankResult>;
+}

package/src/domains/providers/types/target-descriptor.ts

@@ -0,0 +1,38 @@
+import type { CapabilityFlags } from "./capability-flags.js";
+
+export interface TargetAuth {
+	apiKeyEnvVar?: string;
+	apiKeyRef?: string;
+	oauthProfile?: string;
+	headers?: Record<string, string>;
+}
+
+export interface TargetPricing {
+	input: number;
+	output: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+// "clio-managed" is a settings.yaml enum value, not an artifact name; it stays
+// unrenamed by rebrand decision so existing `lifecycle:` lines keep working.
+export type TargetLifecycle = "user-managed" | "clio-managed";
+
+/**
+ * Persisted target specification from settings.yaml (`targets:`). It binds a
+ * user-facing target id to a RuntimeDescriptor id, target URL/auth metadata,
+ * model defaults, and capability overrides. Runtime resolution combines this
+ * spec with the registry/catalog to produce a ResolvedRuntimeTarget.
+ */
+export interface TargetDescriptor {
+	id: string;
+	runtime: string;
+	url?: string;
+	auth?: TargetAuth;
+	defaultModel?: string;
+	wireModels?: string[];
+	capabilities?: Partial<CapabilityFlags>;
+	lifecycle?: TargetLifecycle;
+	gateway?: boolean;
+	pricing?: TargetPricing;
+}

package/src/domains/resources/collision.ts

@@ -0,0 +1,92 @@
+export type ResourceScope = "package" | "user" | "project" | "cli";
+
+export interface ResourceSourceInfo {
+	path: string;
+	scope: ResourceScope;
+	source?: string;
+	/**
+	 * Collision rank, higher wins, for kinds that split a scope into tiers the
+	 * way skills split user roots into compatibility and Clio's own. Set it for
+	 * every candidate of a kind or none of them; a mixed set compares two scales.
+	 */
+	precedence?: number;
+}
+
+export interface ResourceCollision {
+	name: string;
+	winnerPath: string;
+	loserPath: string;
+	winnerScope: ResourceScope;
+	loserScope: ResourceScope;
+}
+
+export interface ResourceDiagnostic {
+	type: "warning" | "error" | "collision";
+	message: string;
+	path?: string;
+	collision?: ResourceCollision;
+}
+
+export interface ResourceCandidate<T> {
+	name: string;
+	value: T;
+	source: ResourceSourceInfo;
+}
+
+export interface CollisionResolution<T> {
+	winners: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+const SCOPE_RANK: Record<ResourceScope, number> = {
+	package: 0,
+	user: 1,
+	project: 2,
+	cli: 3,
+};
+
+function rankOf(info: ResourceSourceInfo): number {
+	return info.precedence ?? SCOPE_RANK[info.scope];
+}
+
+function compareCandidates<T>(a: ResourceCandidate<T>, b: ResourceCandidate<T>): number {
+	const rankDelta = rankOf(a.source) - rankOf(b.source);
+	if (rankDelta !== 0) return rankDelta;
+	return a.source.path.localeCompare(b.source.path);
+}
+
+export function resolveResourceCollisions<T>(candidates: ReadonlyArray<ResourceCandidate<T>>): CollisionResolution<T> {
+	const byName = new Map<string, ResourceCandidate<T>[]>();
+	for (const candidate of candidates) {
+		const key = candidate.name.trim();
+		if (key.length === 0) continue;
+		const list = byName.get(key) ?? [];
+		list.push(candidate);
+		byName.set(key, list);
+	}
+
+	const winners: T[] = [];
+	const diagnostics: ResourceDiagnostic[] = [];
+	for (const [name, entries] of byName.entries()) {
+		const sorted = [...entries].sort(compareCandidates);
+		const winner = sorted[sorted.length - 1];
+		if (!winner) continue;
+		winners.push(winner.value);
+		for (const loser of sorted.slice(0, -1)) {
+			diagnostics.push({
+				type: "collision",
+				message: `${name} from ${winner.source.scope} overrides ${loser.source.scope}`,
+				path: loser.source.path,
+				collision: {
+					name,
+					winnerPath: winner.source.path,
+					loserPath: loser.source.path,
+					winnerScope: winner.source.scope,
+					loserScope: loser.source.scope,
+				},
+			});
+		}
+	}
+
+	return { winners, diagnostics };
+}

package/src/domains/resources/common-loader.ts

@@ -0,0 +1,140 @@
+import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { clioConfigDir } from "../../core/xdg.js";
+import { type ExtensionResourceKind, enabledExtensionResourceRoots } from "../extensions/index.js";
+import type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
+
+export interface ResourceRoot {
+	path: string;
+	scope: ResourceScope;
+	source?: string;
+	/** Collision rank, higher wins. See {@link ResourceSourceInfo.precedence}. */
+	precedence?: number;
+	/** Whether the resource is usable without an explicit trust opt-in. Defaults to true. */
+	trusted?: boolean;
+}
+
+/**
+ * Collision tiers shared by every compatibility-aware resource kind. They match
+ * the skill precedence table so a foreign prompt root ranks against Clio's own
+ * roots exactly the way a foreign skill root does.
+ */
+export const COMPAT_RESOURCE_PRECEDENCE = {
+	extension: 10,
+	userCompat: 20,
+	user: 30,
+	projectCompat: 40,
+	project: 50,
+} as const;
+
+export type FrontmatterSplitResult =
+	| {
+			ok: true;
+			frontmatter: Record<string, unknown>;
+			body: string;
+	  }
+	| {
+			ok: false;
+			reason: string;
+			body: string;
+	  };
+
+export function defaultScopedResourceRoots(kind: ExtensionResourceKind, cwd: string): ResourceRoot[] {
+	return [
+		...enabledExtensionResourceRoots(kind, cwd).map((root) => ({
+			path: root.path,
+			scope: "package" as const,
+			source: root.source,
+			precedence: COMPAT_RESOURCE_PRECEDENCE.extension,
+		})),
+		{
+			path: path.join(clioConfigDir(), kind),
+			scope: "user" as const,
+			source: "config",
+			precedence: COMPAT_RESOURCE_PRECEDENCE.user,
+		},
+		{
+			path: path.join(cwd, ".clio-coder", kind),
+			scope: "project" as const,
+			source: "project",
+			precedence: COMPAT_RESOURCE_PRECEDENCE.project,
+		},
+	];
+}
+
+export function sourceInfoForRoot(root: ResourceRoot, filePath: string): ResourceSourceInfo {
+	return {
+		path: filePath,
+		scope: root.scope,
+		...(root.source ? { source: root.source } : {}),
+		...(root.precedence !== undefined ? { precedence: root.precedence } : {}),
+	};
+}
+
+export function readRootEntries(
+	root: ResourceRoot,
+	label: string,
+	diagnostics: ResourceDiagnostic[],
+): Dirent<string>[] {
+	if (!existsSync(root.path)) return [];
+	let stat: ReturnType<typeof statSync>;
+	try {
+		stat = statSync(root.path);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		diagnostics.push({
+			type: "warning",
+			message: `${label} root could not be stat'ed: ${reason}`,
+			path: root.path,
+		});
+		return [];
+	}
+	if (!stat.isDirectory()) {
+		diagnostics.push({ type: "warning", message: `${label} root is not a directory`, path: root.path });
+		return [];
+	}
+
+	try {
+		return readdirSync(root.path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		diagnostics.push({ type: "warning", message: `${label} root could not be read: ${reason}`, path: root.path });
+		return [];
+	}
+}
+
+export function splitYamlFrontmatter(raw: string): FrontmatterSplitResult {
+	const opening = raw.match(/^---\r?\n/);
+	if (!opening) return { ok: false, reason: "missing", body: raw };
+
+	const closeRegex = /\r?\n---(?:\r?\n|$)/g;
+	closeRegex.lastIndex = opening[0].length;
+	const closing = closeRegex.exec(raw);
+	if (!closing) return { ok: false, reason: "missing closing delimiter", body: raw };
+
+	const body = raw.slice(closing.index + closing[0].length);
+	const frontmatterText = raw.slice(opening[0].length, closing.index);
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(frontmatterText);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		return { ok: false, reason: `invalid YAML: ${reason}`, body };
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { ok: false, reason: "must be a YAML object", body };
+	}
+
+	return {
+		ok: true,
+		frontmatter: parsed as Record<string, unknown>,
+		body,
+	};
+}
+
+export function stringField(frontmatter: Record<string, unknown>, key: string): string | null {
+	const value = frontmatter[key];
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}

package/src/domains/resources/contract.ts

@@ -0,0 +1,25 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type { PendingSkillRequest } from "../../core/skill-activation.js";
+import type { ResourceDiagnostic } from "./collision.js";
+import type { PromptTemplate, PromptTemplateExpansion } from "./prompts/loader.js";
+import type { Skill, SkillExpansion, SkillExpansionOptions } from "./skills/loader.js";
+
+export interface ResourceList<T> {
+	items: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+export interface ResourcesContract extends DomainContract {
+	skills(cwd?: string): ResourceList<Skill>;
+	expandSkillInvocation(text: string, cwd?: string, options?: SkillExpansionOptions): SkillExpansion;
+	parsePendingSkillRequests(
+		text: string,
+		cwd?: string,
+		options?: SkillExpansionOptions,
+	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
+	prompts(cwd?: string): ResourceList<PromptTemplate>;
+	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
+	themes(): ResourceList<never>;
+	resolvePath(value: string, cwd?: string): string;
+	reload(): Promise<void>;
+}

package/src/domains/resources/extension.ts

@@ -0,0 +1,61 @@
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import type { ConfigContract } from "../config/contract.js";
+import type { ResourcesContract } from "./contract.js";
+import { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
+
+export function createResourcesBundle(
+	context: DomainContext,
+	options: ResourceLoaderOptions = {},
+): DomainBundle<ResourcesContract> {
+	const config = (): ConfigContract | undefined => context.getContract<ConfigContract>("config");
+	const loader = createResourcesLoader({
+		...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+		skills: () => ({
+			...skillOptions(config()?.get().skills.trustProjectCompatRoots === true, options),
+		}),
+	});
+	const extension: DomainExtension = {
+		start() {
+			return undefined;
+		},
+	};
+	const contract: ResourcesContract = {
+		skills(cwd) {
+			return loader.skills(cwd);
+		},
+		expandSkillInvocation(text, cwd, options) {
+			return loader.expandSkillInvocation(text, cwd, options);
+		},
+		parsePendingSkillRequests(text, cwd, options) {
+			return loader.parsePendingSkillRequests(text, cwd, options);
+		},
+		prompts(cwd) {
+			return loader.prompts(cwd);
+		},
+		expandPromptTemplate(text, cwd) {
+			return loader.expandPromptTemplate(text, cwd);
+		},
+		themes() {
+			return loader.themes();
+		},
+		resolvePath(value, cwd) {
+			return loader.resolvePath(value, cwd);
+		},
+		reload() {
+			return loader.reload();
+		},
+	};
+	return { extension, contract };
+}
+
+function skillOptions(
+	trustProjectCompatRoots: boolean,
+	options: ResourceLoaderOptions,
+): ReturnType<NonNullable<ResourceLoaderOptions["skills"]>> {
+	const runtime = options.skills?.() ?? {};
+	return {
+		trustProjectCompatRoots: runtime.trustProjectCompatRoots ?? trustProjectCompatRoots,
+		...(runtime.disableDiscovery !== undefined ? { disableDiscovery: runtime.disableDiscovery } : {}),
+		...(runtime.explicitSkillPaths !== undefined ? { explicitSkillPaths: runtime.explicitSkillPaths } : {}),
+	};
+}

package/src/domains/resources/index.ts

@@ -0,0 +1,74 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createResourcesBundle } from "./extension.js";
+import type { ResourceLoaderOptions } from "./loader.js";
+import { ResourcesManifest } from "./manifest.js";
+
+export const ResourcesDomainModule: DomainModule = {
+	manifest: ResourcesManifest,
+	createExtension: createResourcesBundle,
+};
+
+export function createResourcesDomainModule(options: ResourceLoaderOptions = {}): DomainModule {
+	return {
+		manifest: ResourcesManifest,
+		createExtension: (context) => createResourcesBundle(context, options),
+	};
+}
+
+export type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
+export { resolveResourceCollisions } from "./collision.js";
+export type { ResourceList, ResourcesContract } from "./contract.js";
+export { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
+export { ResourcesManifest } from "./manifest.js";
+export {
+	expandPromptTemplateInput,
+	loadPromptTemplates,
+	type PromptTemplate,
+	type PromptTemplateExpansion,
+	type PromptTemplateList,
+	type PromptTemplateRoot,
+} from "./prompts/loader.js";
+export { parseCommandArgs, substituteArgs } from "./prompts/substitute.js";
+export { parseSkillEvals, type SkillEvalParseResult, type SkillEvalScenario } from "./skills/evals.js";
+export {
+	type InstallSkillInput,
+	type InstallSkillResult,
+	normalizedSkillHash,
+	parseSkillSourceSpec,
+	type SkillSourceSpec,
+	type SkillUpdateReport,
+	type SkillUpdateStatus,
+	type UpdateSkillsInput,
+	updateSkills,
+} from "./skills/install.js";
+export {
+	defaultSkillRoots,
+	expandSkillInvocationInput,
+	type LoadSkillsInput,
+	loadSkills,
+	modelVisibleSkills,
+	parsePendingSkillRequests,
+	parseSkillCommand,
+	type Skill,
+	type SkillExpansion,
+	type SkillList,
+	type SkillProvenance,
+	type SkillRoot,
+	type SkillSource,
+} from "./skills/loader.js";
+export {
+	type DiscoverMarketplaceOptions,
+	discoverMarketplaceSkills,
+	getMarketplaceSkills,
+	installSkill,
+	MARKETPLACE_UNCONFIGURED,
+	type MarketplaceDiscoveryResult,
+	type MarketplaceSkill,
+	type MarketplaceSkillOrigin,
+	type MarketplaceStatus,
+} from "./skills/marketplace.js";
+export {
+	checkSkillDrift,
+	type SkillDriftVerdict,
+	type SkillPinEntry,
+} from "./skills/provenance-pin.js";

package/src/domains/resources/loader.ts

@@ -0,0 +1,86 @@
+import { expandConfigPath } from "../../core/resolve-config-value.js";
+import type { PendingSkillRequest } from "../../core/skill-activation.js";
+import type { ResourceDiagnostic } from "./collision.js";
+import {
+	expandPromptTemplateInput,
+	type LoadPromptTemplatesInput,
+	loadPromptTemplates,
+	type PromptTemplate,
+	type PromptTemplateExpansion,
+} from "./prompts/loader.js";
+import {
+	expandSkillInvocationInput,
+	type LoadSkillsInput,
+	loadSkills,
+	parsePendingSkillRequests,
+	type Skill,
+	type SkillExpansion,
+	type SkillExpansionOptions,
+} from "./skills/loader.js";
+
+export interface ResourceList<T> {
+	items: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+export interface ResourceLoaderOptions {
+	cwd?: string;
+	skills?: () => Pick<LoadSkillsInput, "trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths">;
+}
+
+export interface ResourcesLoader {
+	skills(cwd?: string): ResourceList<Skill>;
+	expandSkillInvocation(text: string, cwd?: string, options?: SkillExpansionOptions): SkillExpansion;
+	parsePendingSkillRequests(
+		text: string,
+		cwd?: string,
+		options?: SkillExpansionOptions,
+	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
+	prompts(cwd?: string): ResourceList<PromptTemplate>;
+	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
+	themes(): ResourceList<never>;
+	resolvePath(value: string, cwd?: string): string;
+	reload(): Promise<void>;
+}
+
+export function createResourcesLoader(options: ResourceLoaderOptions = {}): ResourcesLoader {
+	const defaultCwd = options.cwd ?? process.cwd();
+	const skillOptions = (): Pick<
+		LoadSkillsInput,
+		"trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths"
+	> => options.skills?.() ?? {};
+	// Prompts share the skills opt-in: a project compatibility root is the same
+	// trust decision whichever kind is read out of it.
+	const promptOptions = (cwd: string): LoadPromptTemplatesInput => ({
+		cwd,
+		...(skillOptions().trustProjectCompatRoots !== undefined
+			? { trustProjectCompatRoots: skillOptions().trustProjectCompatRoots === true }
+			: {}),
+	});
+	return {
+		skills(cwd = defaultCwd) {
+			return loadSkills({ cwd, ...skillOptions() });
+		},
+		expandSkillInvocation(text, cwd = defaultCwd, expansionOptions = {}) {
+			return expandSkillInvocationInput(text, loadSkills({ cwd, ...skillOptions() }), expansionOptions);
+		},
+		parsePendingSkillRequests(text, cwd = defaultCwd, expansionOptions = {}) {
+			return parsePendingSkillRequests(text, loadSkills({ cwd, ...skillOptions() }), { cwd, ...expansionOptions });
+		},
+		prompts(cwd = defaultCwd) {
+			return loadPromptTemplates(promptOptions(cwd));
+		},
+		expandPromptTemplate(text, cwd = defaultCwd) {
+			return expandPromptTemplateInput(text, loadPromptTemplates(promptOptions(cwd)));
+		},
+		themes() {
+			return { items: [], diagnostics: [] };
+		},
+		resolvePath(value, cwd = defaultCwd) {
+			return expandConfigPath(value, { cwd });
+		},
+		async reload() {
+			return undefined;
+		},
+	};
+}

package/src/domains/resources/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const ResourcesManifest: DomainManifest = {
+	name: "resources",
+	dependsOn: ["config"],
+};