@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/plugins/types.ts

@@ -0,0 +1,217 @@
+export type PluginScope = "user" | "project";
+export type PluginResourceKind = "skills" | "prompts" | "agents" | "fleets" | "themes";
+export type PluginComponentKind = "prompt" | "agent" | "skill" | "fleet" | "script" | "resource" | "tool";
+export type PluginResources = Partial<Record<PluginResourceKind, string>>;
+
+export interface PluginDiagnostic {
+	type: "warning" | "error";
+	message: string;
+	path?: string;
+	/** Machine-readable reason for writer refusals; message text is unchanged. */
+	code?: PluginDiagnosticCode;
+	/** The reviewed fact that changed, for `stale_plan`. */
+	changed?: { scope: PluginScope; id: string; fact: keyof PluginExpectedCopy; expected: unknown; observed: unknown };
+}
+export type PluginDiagnosticCode = "stale_plan" | "locked" | "dependents";
+
+/**
+ * One reviewed copy fact. Every field present is rechecked inside the writer's
+ * lock before any write; a mismatch refuses with `stale_plan`.
+ */
+export interface PluginExpectedCopy {
+	scope: PluginScope;
+	id: string;
+	/**
+	 * A full snapshot (default) also fails when a fact appears or disappears.
+	 * `partial` checks only the facts listed; reserved for the legacy
+	 * digest-only update path that never reviewed the other facts.
+	 */
+	partial?: boolean;
+	/** Install record present in that scope's state.json. */
+	recorded: boolean;
+	/** Observed full-tree digest, or absent. */
+	tree: "absent" | string;
+	enabled?: boolean;
+	recordedDigest?: string;
+	kind?: LibraryEntryKind;
+	trust?: PackageTrust;
+	/** Compared JSON-equal, so identical bytes with a different origin still stale a plan. */
+	origin?: PluginOrigin;
+}
+export interface PluginExpectedState {
+	copies: PluginExpectedCopy[];
+}
+
+export interface PluginComponent {
+	kind: PluginComponentKind;
+	id: string;
+	path: string;
+	requires?: string[];
+}
+
+export interface ClioPluginConfiguration {
+	manifestVersion: 1;
+	/** Absent in portable bundles means plugin. All kinds share the package lifecycle. */
+	kind?: LibraryEntryKind;
+	requires?: LibraryRequirementRef[];
+	/** Contained Suite v2 files, selected explicitly by `clio-coder eval`. */
+	evals?: Record<string, string>;
+	compatibility?: { clio?: string };
+	resources: PluginResources;
+	components: PluginComponent[];
+}
+
+/** Standard identity stays canonical; `clio` is the validated runtime projection. */
+export interface PluginManifest {
+	$schema: string;
+	name: string;
+	version?: string;
+	description?: string;
+	author?: { name?: string; email?: string; url?: string };
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	extensions?: Record<string, Record<string, unknown>>;
+	clio: ClioPluginConfiguration;
+}
+
+export interface PluginCandidate {
+	path: string;
+	manifestPath?: string;
+	manifest?: PluginManifest;
+	valid: boolean;
+	diagnostics: PluginDiagnostic[];
+	contentDigest?: string;
+	manifestDigest?: string;
+}
+
+/** Format of a foreign package as it was found on disk; author labels never set this. */
+export type ForeignPackageFormat = "portable" | "claude-code" | "codex";
+/**
+ * `interop` is a package imported from an installed local agent; `import` is an
+ * explicit source path or GitHub tree. Both always carry foreign trust.
+ */
+export type PluginOrigin =
+	| string
+	| { kind: "local" | "catalog" | "github"; source: string }
+	| { kind: "interop"; host: string; source: string; format?: ForeignPackageFormat; marketplace?: string }
+	| {
+			kind: "import";
+			source: string;
+			transport: "local" | "github";
+			format: ForeignPackageFormat;
+			host?: string;
+			marketplace?: string;
+	  };
+export function isForeignPluginOrigin(origin: PluginOrigin | undefined): boolean {
+	return typeof origin === "object" && (origin.kind === "interop" || origin.kind === "import");
+}
+export type PackageTrust = "trusted" | "foreign";
+
+export interface PluginProvenance {
+	id: string;
+	scope: PluginScope;
+	sourcePath?: string;
+	canonicalRoot: string;
+	manifestDigest: string;
+	contentDigest: string;
+}
+
+export interface InstalledPlugin {
+	id: string;
+	kind?: LibraryEntryKind;
+	trust?: PackageTrust;
+	name: string;
+	version: string;
+	description: string;
+	scope: PluginScope;
+	rootPath: string;
+	manifestPath: string;
+	enabled: boolean;
+	valid: boolean;
+	compatible: boolean;
+	effective: boolean;
+	loadable: boolean;
+	resources: PluginResources;
+	manifest?: PluginManifest;
+	provenance?: PluginProvenance;
+	observedContentDigest?: string;
+	overriddenBy?: PluginScope;
+	diagnostics: PluginDiagnostic[];
+}
+
+export interface PluginResourceRoot {
+	id: string;
+	scope: PluginScope;
+	path: string;
+	rootPath: string;
+	source: string;
+	provenance: PluginProvenance;
+	generation: number;
+	trust?: PackageTrust;
+}
+
+export interface PluginListOptions {
+	cwd?: string;
+	scope?: PluginScope;
+	all?: boolean;
+}
+
+export interface PluginMutationOptions extends PluginListOptions {
+	expect?: PluginExpectedState;
+}
+
+export interface PluginInstallOptions extends PluginMutationOptions {
+	force?: boolean;
+	expectedDigest?: string;
+	expectedId?: string;
+	expectedVersion?: string;
+	origin?: PluginOrigin;
+	trust?: PackageTrust;
+	expectedKind?: LibraryEntryKind;
+}
+
+/** One kind-aware publication seam for library and interop adapters. */
+export interface LibraryPackageInstallInput extends Omit<PluginInstallOptions, "expectedKind"> {
+	kind: LibraryEntryKind;
+	sourcePath: string;
+	scope: PluginScope;
+	origin: PluginOrigin;
+	trust: PackageTrust;
+}
+
+export interface PluginMutationResult {
+	plugin?: InstalledPlugin;
+	removed?: { id: string; scope: PluginScope; path: string };
+	recovery?: { stateBackup?: string; packageBackup?: string };
+	diagnostics: PluginDiagnostic[];
+}
+
+export type PluginInstallResult = PluginMutationResult;
+
+export interface PluginInstallRecord {
+	kind?: LibraryEntryKind;
+	installedAt: string;
+	source: string;
+	origin?: PluginOrigin;
+	contentDigest: string;
+	trust?: PackageTrust;
+}
+
+export interface PluginState {
+	version: 1;
+	disabled: string[];
+	installed: Record<string, PluginInstallRecord>;
+}
+
+export interface PluginSnapshot {
+	version: 1;
+	generation: number;
+	cwd: string;
+	digest: string;
+	packages: ReadonlyArray<InstalledPlugin>;
+	resourceRoots: Readonly<Record<PluginResourceKind, ReadonlyArray<PluginResourceRoot>>>;
+}
+
+import type { LibraryEntryKind, LibraryRequirementRef } from "../resources/library-types.js";

package/src/domains/prompts/extension.ts

@@ -205,7 +205,7 @@ export function createPromptsBundle(
 
 	let unsubscribeContextSources: (() => void) | null = null;
 	let unsubscribeHotReload: (() => void) | null = null;
-	let unsubscribeExtensionsReload: (() => void) | null = null;
+	let unsubscribePluginsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			try {
@@ -226,21 +226,15 @@ export function createPromptsBundle(
 				if (!diffTouchesFragments(paths)) return;
 				reload();
 			});
-			// Extension prompt and skill roots feed fragments through the
-			// resources domain; a committed generation with new content means
-			// the table must be rebuilt from the new roots.
-			unsubscribeExtensionsReload = context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
-				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
-				reload();
-			});
+			unsubscribePluginsReload = context.bus.on(BusChannels.PluginsReloaded, () => reload());
 		},
 		async stop() {
 			unsubscribeContextSources?.();
 			unsubscribeContextSources = null;
 			unsubscribeHotReload?.();
 			unsubscribeHotReload = null;
-			unsubscribeExtensionsReload?.();
-			unsubscribeExtensionsReload = null;
+			unsubscribePluginsReload?.();
+			unsubscribePluginsReload = null;
 			sessionSourceSnapshots.clear();
 		},
 	};

package/src/domains/prompts/fragments/operating/skills.md

@@ -7,13 +7,13 @@ description: Coordinator skill suggestion discipline; rendered only when context
 # Skills
 
 Skills are operator-activated workflows: git delivery, planning, coding
-practice, context priming and handoff, research, and plan stress-testing.
-context (scope="skills") is the one authoritative listing of installed
-and marketplace skills; never guess the inventory or search the
-repository for one. When a task has one of those shapes, list them,
-suggest the best match as /skill <name> (the sequence in order when
-several compose), and continue the task without it: only the operator
-activates or installs a skill, and a [Marketplace] reminder states its
-own offer options. When the operator names a skill or asks how one
-works, answer from that listing. If nothing fits, proceed normally and
-suggest nothing.
+practice, context priming/handoff, research, plan stress-testing.
+context (scope="skills") lists installed and marketplace skills; never
+guess it or search the repository for one. When a task has one of those
+shapes, list them, suggest the best match as /skill <name> (in order
+when several compose), and continue without it: only the operator
+activates or installs a skill; a [Marketplace] reminder states its
+own offer options. When the operator names a skill or asks how it
+works, answer from it. If nothing fits, suggest none. context
+(scope="library") is the read-only catalog of recipes and installable
+packages; it activates nothing.

package/src/domains/providers/cache-deployment.ts

@@ -0,0 +1,147 @@
+import { canonicalEndpointUrl } from "../../core/endpoint-key.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+/** Fresh observations, not a persisted cache handle or permission to administer a server. */
+export interface CacheDeploymentObservation {
+	observedAt: number;
+	backend: "llamacpp" | "vllm" | "unknown";
+	model: string;
+	build: string | null;
+	/** Absent server epoch stays unknown; Clio never invents one from a build number. */
+	epoch: string | null;
+	endpoint: string | null;
+	requestControls: ReadonlyArray<"cache_prompt">;
+	warm: "bounded" | "unsupported";
+	administration: "unsupported";
+	reason: string;
+}
+
+function record(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/**
+ * Read-only admission evidence. Every invocation probes again, so an old route,
+ * build, resident state or process epoch is never reused to authorize a warm.
+ * Control-plane credentials are deliberately independent: this initial reader
+ * sends none. An authenticated/unknown control plane remains passive.
+ */
+export async function observeCacheDeployment(
+	target: TargetDescriptor,
+	wireModelId: string,
+	options: { signal?: AbortSignal; gatewayApiKey?: string; fetchImpl?: typeof fetch } = {},
+): Promise<CacheDeploymentObservation> {
+	const binding = target.cache?.deployment;
+	const observation: CacheDeploymentObservation = {
+		observedAt: Date.now(),
+		backend: binding?.backend ?? "unknown",
+		model: binding?.model ?? wireModelId,
+		build: null,
+		epoch: null,
+		endpoint: null,
+		requestControls: [],
+		warm: "unsupported",
+		administration: "unsupported",
+		reason: "deployment-unbound",
+	};
+	if (!binding) return observation;
+	try {
+		const control = new URL(binding.controlUrl);
+		if (
+			!["http:", "https:"].includes(control.protocol) ||
+			control.username ||
+			control.password ||
+			control.search ||
+			control.hash
+		) {
+			return { ...observation, reason: "deployment-invalid" };
+		}
+		const root = control.href.replace(/\/$/, "").replace(/\/v1$/, "");
+		observation.endpoint = canonicalEndpointUrl(root);
+		const signal = AbortSignal.any([AbortSignal.timeout(2000), ...(options.signal ? [options.signal] : [])]);
+		const get = async (url: string, headers?: Record<string, string>) => {
+			const response = await (options.fetchImpl ?? fetch)(url, {
+				method: "GET",
+				signal,
+				redirect: "error",
+				credentials: "omit",
+				...(headers ? { headers } : {}),
+			});
+			if (!response.ok) throw new Error("discovery unavailable");
+			return (await response.json()) as unknown;
+		};
+		const gateway = target.runtime === "litellm";
+		if (gateway) {
+			if (!binding.gatewayDeploymentId || !target.url) return { ...observation, reason: "gateway-unbound" };
+			const gatewayRoot = target.url.replace(/\/$/, "").replace(/\/v1$/, "");
+			const info = record(
+				await get(`${gatewayRoot}/v1/model/info`, {
+					...target.auth?.headers,
+					...(options.gatewayApiKey ? { authorization: `Bearer ${options.gatewayApiKey}` } : {}),
+				}),
+			);
+			const rows = Array.isArray(info.data) ? info.data.map(record).filter((row) => row.model_name === wireModelId) : [];
+			// Multiple replicas/fallback routes do not establish a single physical
+			// cache. A deployment response header arrives too late for admission.
+			const row = rows.length === 1 ? rows[0] : undefined;
+			const params = record(row?.litellm_params);
+			const modelInfo = record(row?.model_info);
+			if (
+				!row ||
+				modelInfo.id !== binding.gatewayDeploymentId ||
+				(params.model !== binding.model && params.model !== `openai/${binding.model}`) ||
+				canonicalEndpointUrl(typeof params.api_base === "string" ? params.api_base : undefined) !== observation.endpoint
+			) {
+				return { ...observation, reason: "gateway-route-mismatch" };
+			}
+		} else if (
+			target.runtime !== binding.backend ||
+			wireModelId !== binding.model ||
+			canonicalEndpointUrl(target.url) !== observation.endpoint
+		) {
+			return { ...observation, reason: "deployment-mismatch" };
+		}
+		if (binding.backend === "vllm") {
+			const version = record(await get(`${root}/version`));
+			observation.build = typeof version.version === "string" ? version.version : null;
+			// APC and queue/memory metrics vary by deployment. A version and an
+			// OpenAI schema alone establish neither APC nor safe speculative load.
+			return {
+				...observation,
+				reason: observation.build === binding.build ? "vllm-scheduler-unverified" : "deployment-build-mismatch",
+			};
+		}
+		let props = record(await get(`${root}/props`));
+		const router = props.role === "router";
+		if (router) {
+			const models = record(await get(`${root}/models`));
+			const selected = Array.isArray(models.data)
+				? models.data.map(record).find((row) => row.id === binding.model)
+				: undefined;
+			if (record(selected?.status).value !== "loaded") return { ...observation, reason: "model-not-loaded" };
+			// Never wake sleeping models or load an absent worker during discovery.
+			props = record(await get(`${root}/props?model=${encodeURIComponent(binding.model)}&autoload=false`));
+		}
+		observation.build = typeof props.build_info === "string" ? props.build_info : null;
+		if (observation.build !== binding.build) return { ...observation, reason: "deployment-build-mismatch" };
+		if (!observation.build.endsWith("-c841aee"))
+			return { ...observation, reason: "deployment-cache-protocol-unverified" };
+		if (props.is_sleeping !== false) return { ...observation, reason: "model-not-loaded" };
+		if (typeof props.model_alias === "string" && props.model_alias !== binding.model)
+			return { ...observation, reason: "deployment-model-mismatch" };
+		if (!router) {
+			const models = record(await get(`${root}/v1/models`));
+			if (!Array.isArray(models.data) || models.data.length !== 1 || record(models.data[0]).id !== binding.model)
+				return { ...observation, reason: "deployment-model-mismatch" };
+		}
+		if (typeof props.start_time === "string") observation.epoch = props.start_time;
+		const slots = await get(`${root}/slots?model=${encodeURIComponent(binding.model)}&autoload=false`);
+		if (!Array.isArray(slots) || slots.length === 0 || slots.some((slot) => record(slot).is_processing !== false)) {
+			return { ...observation, reason: "endpoint-busy-or-unknown" };
+		}
+		if (gateway) return { ...observation, reason: "gateway-cache-transport-unverified" };
+		return { ...observation, requestControls: ["cache_prompt"], warm: "bounded", reason: "loaded-idle-deployment" };
+	} catch {
+		return { ...observation, reason: options.signal?.aborted ? "superseded" : "deployment-unavailable" };
+	}
+}

package/src/domains/providers/catalog.ts

@@ -148,7 +148,7 @@ export function synthesizeCatalogBackedModel(input: CatalogBackedSynthesisInput)
 	}
 	const pricing = input.target.pricing;
 	const targetHeaders = input.target.auth?.headers;
-	const model: Model<Api> = {
+	const model: Model<Api> & { clioCoder?: { cache: NonNullable<TargetDescriptor["cache"]> } } = {
 		...catalogFields,
 		id: input.wireModelId,
 		name: `${input.wireModelId} (${input.target.id})`,
@@ -160,14 +160,19 @@ export function synthesizeCatalogBackedModel(input: CatalogBackedSynthesisInput)
 			input.defaultBaseUrl,
 		reasoning: caps.reasoning,
 		input: caps.vision ? (builtin?.input.includes("image") ? builtin.input : ["text", "image"]) : ["text"],
-		cost: {
-			input: pricing?.input ?? builtin?.cost.input ?? 0,
-			output: pricing?.output ?? builtin?.cost.output ?? 0,
-			cacheRead: pricing?.cacheRead ?? builtin?.cost.cacheRead ?? 0,
-			cacheWrite: pricing?.cacheWrite ?? builtin?.cost.cacheWrite ?? 0,
-		},
+		// Catalog tiers belong to the catalog rates. An explicit target price
+		// replaces that schedule, using the same defaults as resolveEffectivePricing.
+		cost: pricing
+			? {
+					input: pricing.input,
+					output: pricing.output,
+					cacheRead: pricing.cacheRead ?? 0,
+					cacheWrite: pricing.cacheWrite ?? 0,
+				}
+			: structuredClone(builtin?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }),
 		contextWindow: caps.contextWindow,
 		maxTokens: caps.maxTokens,
+		...(input.target.cache === undefined ? {} : { clioCoder: { cache: structuredClone(input.target.cache) } }),
 	};
 	const headers = { ...(input.defaultHeaders ?? {}), ...(builtin?.headers ?? {}), ...(targetHeaders ?? {}) };
 	if (Object.keys(headers).length > 0) {

package/src/domains/providers/extension.ts

@@ -257,6 +257,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 	const statuses = new Map<string, TargetStatus>();
 	const reasoningCache = new Map<string, boolean>();
 	const unsubscribeConfigListeners: Array<() => void> = [];
+	let stopped = false;
 
 	function reasoningCacheKey(targetId: string, modelId: string): string {
 		return `${targetId}:${modelId}`;
@@ -268,6 +269,11 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		return readSettings();
 	}
 
+	function currentProbeTarget(probed: TargetDescriptor): TargetDescriptor | undefined {
+		if (stopped) return undefined;
+		return readConfig().targets.find((target) => sameProbeIdentity(probed, target));
+	}
+
 	async function buildProbeContextForTarget(
 		target: TargetDescriptor,
 		desc: RuntimeDescriptor,
@@ -323,6 +329,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		probe: ProbeResult | null,
 		previous?: TargetStatus,
 	): TargetStatus {
+		if (previous && !sameProbeIdentity(previous.target, target)) previous = undefined;
 		if (!desc) {
 			const out: TargetStatus = {
 				target,
@@ -385,8 +392,11 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		target: TargetDescriptor,
 		live: boolean,
 		options?: { reasoning?: boolean; signal?: AbortSignal },
-	): Promise<TargetStatus> {
+	): Promise<TargetStatus | null> {
 		options?.signal?.throwIfAborted();
+		if (stopped) return null;
+		// A probe owns the descriptor it started with across asynchronous I/O.
+		target = structuredClone(target);
 		const previous = statuses.get(target.id);
 		const desc = registry.get(target.runtime);
 		if (!desc) {
@@ -402,6 +412,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		}
 		const probeCtx = await buildProbeContextForTarget(target, desc, options?.signal);
 		options?.signal?.throwIfAborted();
+		if (!currentProbeTarget(target)) return null;
 		let probeResult: ProbeResult;
 		try {
 			probeResult = await desc.probe(target, probeCtx);
@@ -409,6 +420,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			probeResult = { ok: false, error: err instanceof Error ? err.message : String(err) };
 		}
 		options?.signal?.throwIfAborted();
+		if (!currentProbeTarget(target)) return null;
 		if (probeResult.ok && typeof desc.probeModels === "function" && !probeResult.models) {
 			try {
 				const ids = await desc.probeModels(target, probeCtx);
@@ -418,6 +430,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			}
 		}
 		options?.signal?.throwIfAborted();
+		if (!currentProbeTarget(target)) return null;
 		if (probeResult.ok && options?.reasoning !== false && typeof desc.probeReasoning === "function") {
 			const settings = readConfig();
 			const orchestratorTarget = settings.chat.target === target.id ? settings.chat.model : null;
@@ -426,6 +439,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 				try {
 					const result = await desc.probeReasoning(target, candidateModelId, probeCtx);
 					options?.signal?.throwIfAborted();
+					if (!currentProbeTarget(target)) return null;
 					reasoningCache.set(reasoningCacheKey(target.id, candidateModelId), result.reasoning);
 					const capabilityModelId = probeResult.capabilityModelId ?? null;
 					if (capabilityModelId === null || capabilityModelId === candidateModelId) {
@@ -447,9 +461,11 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 				}
 			}
 		}
-		// A cancelled role preparation must not publish failed/stale target state.
+		// Cancellation, target edits/removal, and shutdown revoke publication.
 		options?.signal?.throwIfAborted();
-		const status = buildStatus(target, desc, probeResult, previous);
+		const current = currentProbeTarget(target);
+		if (!current) return null;
+		const status = buildStatus(current, desc, probeResult, previous);
 		statuses.set(target.id, status);
 		if (probeResult.ok && probeResult.models !== undefined) {
 			recordTargetModelSnapshot(
@@ -467,14 +483,18 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 	}
 
 	async function probeReasoningForModelInternal(targetId: string, modelId: string): Promise<boolean | null> {
+		if (stopped) return null;
 		const settings = readConfig();
-		const target = settings.targets.find((ep) => ep.id === targetId);
-		if (!target) return null;
+		const configuredTarget = settings.targets.find((ep) => ep.id === targetId);
+		if (!configuredTarget) return null;
+		const target = structuredClone(configuredTarget);
 		const desc = registry.get(target.runtime);
 		if (!desc || typeof desc.probeReasoning !== "function") return null;
 		const probeCtx = await buildProbeContextForTarget(target, desc);
+		if (!currentProbeTarget(target)) return null;
 		try {
 			const result = await desc.probeReasoning(target, modelId, probeCtx);
+			if (!currentProbeTarget(target)) return null;
 			reasoningCache.set(reasoningCacheKey(targetId, modelId), result.reasoning);
 			return result.reasoning;
 		} catch {
@@ -508,6 +528,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 
 	const extension: DomainExtension = {
 		async start() {
+			stopped = false;
 			ensurePiAiRegistered();
 			registerClioApiProviders();
 			registerClioOAuthProviders();
@@ -528,6 +549,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			}
 		},
 		async stop() {
+			stopped = true;
 			for (const unsubscribe of unsubscribeConfigListeners.splice(0)) unsubscribe();
 		},
 	};

package/src/domains/providers/index.ts

@@ -24,6 +24,7 @@ export {
 	resolveRuntimeAuthTarget,
 	targetRequiresAuth,
 } from "./auth/index.js";
+export { type CacheDeploymentObservation, observeCacheDeployment } from "./cache-deployment.js";
 export { AGENT_ROLE_TOOLS_REQUIRED_REASON, mergeCapabilities, supportsAgentRoleTools } from "./capabilities.js";
 export type { ProvidersContract, TargetHealth, TargetStatus } from "./contract.js";
 export { isDispatchEligibleRuntime, isOrchestratorEligibleRuntime, isTargetEligibleRuntime } from "./eligibility.js";

package/src/domains/providers/plugins.ts

@@ -14,29 +14,19 @@
 
 import { join } from "node:path";
 
+import type { ClioSettings } from "../../core/config.js";
 import { clioConfigDir } from "../../core/xdg.js";
 import { activateExternalPluginApiBridge } from "../../engine/api-registry.js";
 import type { RuntimeRegistry } from "./registry.js";
 
-interface PluginSettings {
-	runtimePlugins?: unknown;
-}
-
-function extractPluginPackages(settings: unknown): string[] {
-	if (!settings || typeof settings !== "object") return [];
-	const raw = (settings as PluginSettings).runtimePlugins;
-	if (!Array.isArray(raw)) return [];
-	return raw.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
-}
-
 export async function loadPluginRuntimes(
 	registry: RuntimeRegistry,
-	settings?: unknown,
+	settings?: Pick<ClioSettings, "integrations">,
 ): Promise<ReadonlyArray<string>> {
 	const loaded: string[] = [];
 
 	const pluginDir = join(clioConfigDir(), "runtimes");
-	const packages = extractPluginPackages(settings);
+	const packages = settings?.integrations.runtimePlugins ?? [];
 	try {
 		const ids = await registry.loadFromDir(pluginDir, activateExternalPluginApiBridge);
 		loaded.push(...ids);

package/src/domains/providers/runtimes/common/local-synth.ts

@@ -25,6 +25,7 @@ export interface ClioLocalModelMetadata {
 		chatTemplateKwargsUnsupported?: boolean;
 		lmstudio?: TargetDescriptor["lmstudio"];
 		litellm?: TargetDescriptor["litellm"];
+		cache?: TargetDescriptor["cache"];
 	};
 }
 
@@ -65,6 +66,8 @@ function localOpenAICompat(caps: CapabilityFlags, runtimeId: string): OpenAIComp
 		maxTokensField: "max_tokens",
 		supportsThinkingTokenBudget: runtimeId === "vllm",
 		supportsStrictMode: false,
+		// Native and generic gateway schemas do not establish hosted 24h retention.
+		supportsLongCacheRetention: false,
 	};
 	const thinkingFormat = openAIThinkingFormat(caps);
 	if (thinkingFormat) (compat as unknown as { thinkingFormat?: string }).thinkingFormat = thinkingFormat;
@@ -111,6 +114,7 @@ export function synthLocalModel(input: LocalSynthesisInput): Model<Api> {
 			...(quirks ? { quirks } : {}),
 			...(target.lmstudio ? { lmstudio: target.lmstudio } : {}),
 			...(target.litellm ? { litellm: target.litellm } : {}),
+			...(target.cache ? { cache: structuredClone(target.cache) } : {}),
 		},
 	};
 	if (headers) model.headers = headers;