@iowarp/clio-coder 0.4.4 → 0.4.6

package/src/domains/prompts/preload.ts

@@ -1,82 +1,156 @@
-/**
- * Project-context preload classification. One place owns the preload cliff:
- * the session compiler uses it to choose a full effective-handbook preload versus compact
- * synopsis, and reporting surfaces (context-init output, `clio-coder config
- * inspect`, the context-window overlay) use it to make the cliff visible.
- */
+import type { ProjectPromptContext } from "../context/contract.js";
+import { renderProjectContextFragment } from "../context/index.js";
+import { sha256 } from "./hash.js";
+import { safePrefixOffsets, sourceLineCount } from "./preload-prefix.js";
 
+/** Historical limits, measured in UTF-16 code units and rendered lines. */
 export const FULL_PROJECT_CONTEXT_MAX_CHARS = 8000;
 export const FULL_PROJECT_CONTEXT_MAX_LINES = 220;
-
-/** Fraction of a limit at which a full preload is flagged as near the cliff. */
-const NEAR_LIMIT_FRACTION = 0.9;
-
-export type ProjectPreloadMode = "full" | "synopsis" | "none";
+export type ProjectPreloadMode = "full" | "partial" | "synopsis" | "none";
 export type ProjectPreloadReason = "size" | "lines" | "no-clio-md";
-
+export interface ProjectPreloadSource {
+	path: string;
+	contentHash: string;
+	availableChars: number;
+	availableLines: number;
+	includedChars: number;
+	includedLines: number;
+	includedRange: [number, number] | null;
+	omittedRange: [number, number] | null;
+	omissionReason: "budget" | null;
+}
 export interface ProjectPreloadClass {
 	mode: ProjectPreloadMode;
-	/** Rendered project-context length in characters (untrimmed, as measured by the cliff). */
+	/** Available rendered UTF-16 code units; retained for historical readers. */
 	chars: number;
-	/** Rendered project-context line count. */
+	/** Available rendered lines, including the final split segment. */
 	lines: number;
-	/** Which limit forced the synopsis; null for full or none. */
 	reason: ProjectPreloadReason | null;
-	/** True when a full preload is within 10% of either limit. */
 	nearLimit: boolean;
-	/** Human line, e.g. "full (5.2kB, 130 lines)" or "synopsis (reason: size)". */
 	label: string;
+	/** Additive snapshot accounting; absent in historical full/synopsis records. */
+	includedChars?: number;
+	includedLines?: number;
+	sources?: ProjectPreloadSource[];
+	omittedSupportFragments?: number;
+	providerSupportsTools?: boolean | null;
 }
+const renderedLines = (text: string): number => (text.length === 0 ? 0 : text.split("\n").length);
 
-export interface ClassifyProjectPreloadInput {
-	/** True when at least one selected project handbook contributed to the rendered text. */
-	hasClioMd: boolean;
-	/** The rendered project prompt context (ProjectPromptContext.text). */
-	text: string;
-}
-
-function formatKb(chars: number): string {
-	return `${(chars / 1000).toFixed(1)}kB`;
+function coverage(path: string, source: string, included: string): ProjectPreloadSource {
+	const availableLines = sourceLineCount(source);
+	const includedLines = sourceLineCount(included);
+	return {
+		path,
+		contentHash: sha256(source),
+		availableChars: source.length,
+		availableLines,
+		includedChars: included.length,
+		includedLines,
+		includedRange: includedLines === 0 ? null : [1, includedLines],
+		omittedRange: included.length === source.length ? null : [includedLines + 1, availableLines],
+		omissionReason: included.length === source.length ? null : "budget",
+	};
 }
 
-/**
- * Classify how the session compiler will treat this project context. Must
- * mirror the selection in prompts/extension.ts exactly: full preload only
- * when a selected project handbook parses and the rendered text is within both the
- * char and line limits; empty text preloads nothing.
- */
-export function classifyProjectPreload(input: ClassifyProjectPreloadInput): ProjectPreloadClass {
-	const chars = input.text.length;
-	const lines = input.text.length === 0 ? 0 : input.text.split("\n").length;
-	if (input.text.trim().length === 0) {
-		return { mode: "none", chars, lines, reason: null, nearLimit: false, label: "none (no project context)" };
-	}
-	const reason: ProjectPreloadReason | null = !input.hasClioMd
-		? "no-clio-md"
-		: chars > FULL_PROJECT_CONTEXT_MAX_CHARS
-			? "size"
-			: lines > FULL_PROJECT_CONTEXT_MAX_LINES
-				? "lines"
-				: null;
-	if (reason !== null) {
+/** One selector owns delivered text and reporting; it never re-parses authored markers. */
+export function selectProjectPreload(
+	context: ProjectPromptContext,
+	providerSupportsTools: boolean | null = null,
+	options: { maxChars?: number; externalReadTools?: boolean } = {},
+): { text: string; classification: ProjectPreloadClass } {
+	const maxChars = options.maxChars ?? FULL_PROJECT_CONTEXT_MAX_CHARS;
+	const fits = (text: string): boolean =>
+		text.length <= maxChars && renderedLines(text) <= FULL_PROJECT_CONTEXT_MAX_LINES;
+	const chars = context.text.length;
+	const lines = renderedLines(context.text);
+	const classify = (
+		text: string,
+		mode: ProjectPreloadMode,
+		sources: ProjectPreloadSource[],
+		omittedSupportFragments: number,
+	): ProjectPreloadClass => {
+		const includedChars = text.length;
+		const includedLines = renderedLines(text);
+		const incomplete = sources.filter((source) => source.omissionReason !== null).length;
 		return {
-			mode: "synopsis",
+			mode,
 			chars,
 			lines,
-			reason,
-			nearLimit: false,
-			label: `synopsis (reason: ${reason})`,
+			includedChars,
+			includedLines,
+			sources,
+			omittedSupportFragments,
+			providerSupportsTools,
+			reason: mode !== "partial" ? null : chars > maxChars ? "size" : "lines",
+			nearLimit: mode === "full" && (chars > maxChars * 0.9 || lines > FULL_PROJECT_CONTEXT_MAX_LINES * 0.9),
+			label: `${mode} (included ${includedChars}/${chars} UTF-16 units, ${includedLines}/${lines} rendered lines; ${incomplete} of ${sources.length} handbook sources incomplete${providerSupportsTools === null ? "; tool capability unknown" : ""})`,
 		};
-	}
-	const nearLimit =
-		chars > FULL_PROJECT_CONTEXT_MAX_CHARS * NEAR_LIMIT_FRACTION ||
-		lines > FULL_PROJECT_CONTEXT_MAX_LINES * NEAR_LIMIT_FRACTION;
-	return {
-		mode: "full",
-		chars,
-		lines,
-		reason: null,
-		nearLimit,
-		label: `full (${formatKb(chars)}, ${lines} lines)`,
 	};
+	if (fits(context.text)) {
+		const sources = context.handbookSources.map(({ path, source }) => coverage(path, source, source));
+		return {
+			text: context.text,
+			classification: classify(context.text, context.text.length === 0 ? "none" : "full", sources, 0),
+		};
+	}
+	const retrieval =
+		providerSupportsTools === false
+			? "Remaining source text is unavailable to this target and cannot be recovered with tools in this session. Paths are source references."
+			: options.externalReadTools
+				? "External read tools are unknown. If available and permitted, read the listed omitted physical lines with your file-reading tool. Otherwise report the missing guidance to the parent. Reads use current disk content, which may differ from the captured source."
+				: `${providerSupportsTools === null ? "If tools are available, read" : "Read"} each omitted suffix with read({path: ABSOLUTE_PATH, offset: FIRST_OMITTED_LINE, limit: 200}); continue as needed. Reads use current disk content, which may differ from the captured source.`;
+	const header = [
+		"<project-preload>",
+		"Incomplete authored prefixes/excerpts: omitted guidance is not known from this preload. Read the selected sources before relying on project guidance.",
+		retrieval,
+	];
+	const totals = context.handbookSources.map(({ source }) => sourceLineCount(source));
+	const sourceRecord = (path: string, included: string, omitted: string): string =>
+		`${JSON.stringify(path)}: included physical lines ${included}; omitted physical lines ${omitted}.`;
+	const reservedRecords = context.handbookSources.map(({ path }, index) =>
+		sourceRecord(path, `none/${totals[index]}-${totals[index]}`, `none/${totals[index]}-${totals[index]} (budget)`),
+	);
+	const notice = (records: string[], omitted: number): string =>
+		[...header, ...records, `Support fragments omitted: ${omitted}.`, "</project-preload>"].join("\n");
+	const reservedNotice = notice(reservedRecords, context.supportFragments.length);
+	if (!fits(reservedNotice))
+		throw new Error(`project preload metadata-budget overflow for ${context.handbookSources.length} handbook sources`);
+	const excerpts = context.handbookSources.map(() => "");
+	const fragments = context.handbookSources.map(() => "");
+	const assemble = (metadata: string, support: readonly string[] = []): string =>
+		[metadata, ...fragments.filter(Boolean), ...support].join("\n\n");
+	// Allocate nearest first, while fragments retain the original ancestor-first order.
+	for (let index = context.handbookSources.length - 1; index >= 0; index--) {
+		const entry = context.handbookSources[index];
+		if (!entry) continue;
+		const { path, source } = entry;
+		for (const offset of safePrefixOffsets(source, maxChars).slice(1)) {
+			const previous = fragments[index] ?? "";
+			fragments[index] = renderProjectContextFragment(source.slice(0, offset), path);
+			if (!fits(assemble(reservedNotice))) {
+				fragments[index] = previous;
+				break;
+			}
+			excerpts[index] = source.slice(0, offset);
+		}
+	}
+	const support: string[] = [];
+	for (const fragment of context.supportFragments) {
+		if (fits(assemble(reservedNotice, [...support, fragment]))) support.push(fragment);
+	}
+	const sources = context.handbookSources.map(({ path, source }, index) =>
+		coverage(path, source, excerpts[index] ?? ""),
+	);
+	const records = sources.map((source) =>
+		sourceRecord(
+			source.path,
+			source.includedRange?.join("-") ?? "none",
+			source.omittedRange ? `${source.omittedRange.join("-")} (budget)` : "none",
+		),
+	);
+	const omitted = context.supportFragments.length - support.length;
+	const text = assemble(notice(records, omitted), support);
+	if (!fits(text)) throw new Error("project preload budget postcondition failed");
+	return { text, classification: classify(text, "partial", sources, omitted) };
 }

package/src/domains/providers/auth/backend-file.ts

@@ -1,9 +1,9 @@
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { safeResourceWrite } from "../../../core/safe-resource-write.js";
 import { withStateFileLock, withStateFileLockSync } from "../../../core/state-file-lock.js";
-import { clioConfigDir } from "../../../core/xdg.js";
+import { resolveClioDirs } from "../../../core/xdg.js";
 import type { AuthOperationOptions } from "../../../engine/types.js";
 
 import type { AuthStorageBackend, LockResult } from "./storage.js";
@@ -20,7 +20,7 @@ function atomicWriteSecret(absPath: string, contents: string): void {
 }
 
 export function authStoragePath(): string {
-	return join(clioConfigDir(), "credentials.yaml");
+	return join(resolveClioDirs().config, "credentials.yaml");
 }
 
 export class FileAuthStorageBackend implements AuthStorageBackend {
@@ -34,18 +34,23 @@ export class FileAuthStorageBackend implements AuthStorageBackend {
 		mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
 	}
 
-	private ensureFileExists(): void {
-		if (existsSync(this.path)) return;
-		const fd = openSync(this.path, "a", 0o600);
-		closeSync(fd);
-		chmodSync(this.path, 0o600);
+	// Writers publish complete files with an atomic rename, so a reader sees
+	// either the prior or next committed snapshot without creating a lockfile or
+	// initializing a missing home. Read-modify-write operations still take the
+	// exclusive lock below and read again inside it before merging changes.
+	read(): string | undefined {
+		try {
+			return readFileSync(this.path, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
 	}
 
 	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T {
 		this.ensureParentDir();
-		this.ensureFileExists();
 		return withStateFileLockSync(this.path, () => {
-			const current = existsSync(this.path) ? readFileSync(this.path, "utf8") : undefined;
+			const current = this.read();
 			const { result, next } = fn(current);
 			if (next !== undefined) {
 				atomicWriteSecret(this.path, next);
@@ -60,7 +65,6 @@ export class FileAuthStorageBackend implements AuthStorageBackend {
 	): Promise<T> {
 		options?.signal?.throwIfAborted();
 		this.ensureParentDir();
-		this.ensureFileExists();
 		return withStateFileLock(
 			this.path,
 			async () => {

package/src/domains/providers/auth/storage.ts

@@ -38,6 +38,8 @@ export interface LockResult<T> {
 }
 
 export interface AuthStorageBackend {
+	/** A committed snapshot without creating storage or acquiring a write lock. */
+	read?(): string | undefined;
 	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
 	withLockAsync<T>(
 		fn: (current: string | undefined) => Promise<LockResult<T>>,
@@ -305,11 +307,7 @@ export class AuthStorage {
 
 	reload(): void {
 		try {
-			let content: string | undefined;
-			this.backend.withLock((current) => {
-				content = current;
-				return { result: undefined };
-			});
+			const content = this.backend.read ? this.backend.read() : this.backend.withLock((current) => ({ result: current }));
 			const read = readStorageData(content);
 			this.data = read.data;
 			this.damage = read.damage;

package/src/domains/providers/catalog.ts

@@ -122,6 +122,8 @@ export interface CatalogBackedSynthesisInput {
 	runtimeId: string;
 	provider: string;
 	api: Api;
+	/** Use the catalog transport and its endpoint when no explicit target URL is configured. */
+	preferCatalogTransport?: boolean;
 	defaultBaseUrl: string;
 	defaultHeaders?: Record<string, string>;
 }
@@ -134,15 +136,28 @@ export function synthesizeCatalogBackedModel(input: CatalogBackedSynthesisInput)
 		null,
 		input.target.capabilities ?? null,
 	);
+	const api = input.preferCatalogTransport && input.target.url === undefined ? (builtin?.api ?? input.api) : input.api;
+	// A catalog endpoint, compatibility flags, and effort map describe one API.
+	// Explicit endpoints keep the runtime's API contract, even when a catalog
+	// model has moved to another transport (for example OpenRouter Claude).
+	const sameTransport = builtin?.api === api;
+	const catalogFields = { ...builtin };
+	if (input.preferCatalogTransport && !sameTransport) {
+		delete catalogFields.compat;
+		delete catalogFields.thinkingLevelMap;
+	}
 	const pricing = input.target.pricing;
 	const targetHeaders = input.target.auth?.headers;
 	const model: Model<Api> = {
-		...(builtin ?? {}),
+		...catalogFields,
 		id: input.wireModelId,
 		name: `${input.wireModelId} (${input.target.id})`,
-		api: input.api,
+		api,
 		provider: input.provider,
-		baseUrl: input.target.url ?? builtin?.baseUrl ?? input.defaultBaseUrl,
+		baseUrl:
+			input.target.url ??
+			(input.preferCatalogTransport && !sameTransport ? undefined : builtin?.baseUrl) ??
+			input.defaultBaseUrl,
 		reasoning: caps.reasoning,
 		input: caps.vision ? (builtin?.input.includes("image") ? builtin.input : ["text", "image"]) : ["text"],
 		cost: {

package/src/domains/providers/probe/fingerprint.ts

@@ -3,11 +3,15 @@ export interface NativeRuntimeFingerprint {
 	displayName: string;
 }
 
-async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response | null> {
+async function fetchWithTimeout(
+	url: string,
+	timeoutMs: number,
+	headers: Record<string, string>,
+): Promise<Response | null> {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeoutMs);
 	try {
-		return await fetch(url, { signal: controller.signal });
+		return await fetch(url, { signal: controller.signal, headers });
 	} catch {
 		return null;
 	} finally {
@@ -22,10 +26,13 @@ async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Respons
  * by doctor + configure wizard to steer users onto native runtimes for
  * resident-model lifecycle.
  */
-export async function fingerprintNativeRuntime(baseUrl: string): Promise<NativeRuntimeFingerprint | null> {
+export async function fingerprintNativeRuntime(
+	baseUrl: string,
+	headers: Record<string, string> = {},
+): Promise<NativeRuntimeFingerprint | null> {
 	const normalized = baseUrl.replace(/^ws:/u, "http:").replace(/^wss:/u, "https:");
 	const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
-	const greeting = await fetchWithTimeout(`${trimmed}/lmstudio-greeting`, 750);
+	const greeting = await fetchWithTimeout(`${trimmed}/lmstudio-greeting`, 750, headers);
 	if (greeting?.ok) {
 		try {
 			const data = (await greeting.json()) as { lmstudio?: unknown };
@@ -34,7 +41,7 @@ export async function fingerprintNativeRuntime(baseUrl: string): Promise<NativeR
 			// The exact JSON body is the fingerprint.
 		}
 	}
-	const lmStudioV0 = await fetchWithTimeout(`${trimmed}/api/v0/models`, 750);
+	const lmStudioV0 = await fetchWithTimeout(`${trimmed}/api/v0/models`, 750, headers);
 	if (lmStudioV0?.ok) {
 		try {
 			const data = (await lmStudioV0.json()) as { data?: unknown };
@@ -48,7 +55,7 @@ export async function fingerprintNativeRuntime(baseUrl: string): Promise<NativeR
 			// A malformed v0 body is not an LM Studio fingerprint.
 		}
 	}
-	const ollama = await fetchWithTimeout(`${trimmed}/api/version`, 750);
+	const ollama = await fetchWithTimeout(`${trimmed}/api/version`, 750, headers);
 	if (ollama?.ok) {
 		try {
 			const data = (await ollama.json()) as { version?: unknown };

package/src/domains/providers/probe/reasoning.ts

@@ -19,6 +19,7 @@ export interface ProbeReasoningOptions {
 	modelId: string;
 	timeoutMs: number;
 	apiKey?: string;
+	headers?: Record<string, string>;
 	signal?: AbortSignal;
 }
 
@@ -72,6 +73,7 @@ export async function probeOpenAICompatReasoning(opts: ProbeReasoningOptions): P
 
 	const headers: Record<string, string> = { "content-type": "application/json" };
 	if (opts.apiKey && opts.apiKey.length > 0) headers.authorization = `Bearer ${opts.apiKey}`;
+	Object.assign(headers, opts.headers);
 
 	const body = JSON.stringify({
 		model: opts.modelId,

package/src/domains/providers/runtime-resolution.ts

@@ -665,14 +665,16 @@ function positiveWindow(value: number | null | undefined): number | undefined {
  *    (live model hint > knowledge base > catalog > runtime default > 8192).
  *  - `desired`: what Clio wants for coding. Local-native tiers still get a
  *    128k recommendation, but this is advisory only.
- *  - `effective`: what the target actually offers, most live source first:
- *    loaded > probe > target config override > model-specific knowledge >
- *    runtime descriptor default. Clio no longer invents a 128k effective
+ *  - `effective`: the configured target limit, capped by a known loaded window;
+ *    otherwise loaded > probe > model-specific knowledge > runtime descriptor
+ *    default. Clio no longer invents a 128k effective
  *    window for unknown local models; providers must probe it or users must
  *    configure an explicit override.
  *
- * The loaded window outranks everything below it because it is the only figure
- * that describes what the backend will serve this turn. A model whose weights
+ * A loaded window prevents configuration from overstating what the backend can
+ * serve this turn. An operator can also configure a smaller limit, including
+ * when a gateway advertises training capacity instead of serving capacity.
+ * A model whose weights
  * allow 262k but which is open at 100k fails at 100k, so planning against the
  * declared number means autocompact never fires in time.
  *
@@ -718,18 +720,18 @@ export function resolveContextWindowDetails(
 	const overrideWindow = positiveWindow(target.capabilities?.contextWindow);
 	let effective: number;
 	let source: ContextWindowSource;
-	if (loadedWindow !== undefined) {
+	if (loadedWindow !== undefined && (overrideWindow === undefined || loadedWindow <= overrideWindow)) {
 		effective = loadedWindow;
 		source = "loaded";
+	} else if (overrideWindow !== undefined) {
+		effective = overrideWindow;
+		source = "target-override";
 	} else if (probeWindow !== undefined) {
 		effective = probeWindow;
 		// Not "loaded": a probed window is what the target reported for the
 		// model, and only a runtime that names its resident instance's window
 		// has said anything about what is serving right now.
 		source = "probe";
-	} else if (overrideWindow !== undefined) {
-		effective = overrideWindow;
-		source = "target-override";
 	} else if (modelDeclared !== undefined) {
 		effective = modelDeclared;
 		source = modelDeclaredSource;

package/src/domains/providers/runtimes/cloud/openrouter.ts

@@ -82,6 +82,7 @@ const openrouterRuntime: RuntimeDescriptor = {
 	displayName: "OpenRouter",
 	kind: "http",
 	tier: "cloud",
+	// Runtime fallback and explicit-URL contract; dispatch uses each synthesized model.api.
 	apiFamily: "openai-completions",
 	auth: "api-key",
 	credentialsEnvVar: "OPENROUTER_API_KEY",
@@ -101,6 +102,7 @@ const openrouterRuntime: RuntimeDescriptor = {
 			defaultCapabilities,
 			runtimeId: "openrouter",
 			api: "openai-completions",
+			preferCatalogTransport: true,
 			provider: "openrouter",
 			defaultBaseUrl: OPENROUTER_BASE_URL,
 			defaultHeaders: OPENROUTER_HEADERS,

package/src/domains/providers/runtimes/common/probe-helpers.ts

@@ -8,13 +8,27 @@ export interface OpenAIModelsResponse {
 	data?: Array<Record<string, unknown> & { id?: unknown; status?: unknown }>;
 }
 
-export async function probeUrl(url: string, ctx: ProbeContext, method: "GET" | "HEAD" = "GET"): Promise<ProbeResult> {
-	const base = { url, timeoutMs: ctx.httpTimeoutMs, method } as const;
+function bearerHeaders(ctx: ProbeContext): Record<string, string> {
+	return ctx.authToken ? { Authorization: `Bearer ${ctx.authToken}` } : {};
+}
+
+export async function probeUrl(
+	url: string,
+	ctx: ProbeContext,
+	method: "GET" | "HEAD" = "GET",
+	headers: Record<string, string> = bearerHeaders(ctx),
+): Promise<ProbeResult> {
+	const base = { url, timeoutMs: ctx.httpTimeoutMs, method, headers } as const;
 	return ctx.signal ? probeHttp({ ...base, signal: ctx.signal }) : probeHttp(base);
 }
 
-export async function probeOpenAIModels(base: string, ctx: ProbeContext, modelsPath = "/v1/models"): Promise<string[]> {
-	return (await probeOpenAIModelCatalog(base, ctx, modelsPath)).models;
+export async function probeOpenAIModels(
+	base: string,
+	ctx: ProbeContext,
+	modelsPath = "/v1/models",
+	headers: Record<string, string> = bearerHeaders(ctx),
+): Promise<string[]> {
+	return (await probeOpenAIModelCatalog(base, ctx, modelsPath, headers)).models;
 }
 
 export interface OpenAIModelCatalogProbe {
@@ -38,11 +52,12 @@ async function probeModelDetailRows(
 	base: string,
 	ctx: ProbeContext,
 	modelsPath: string,
+	headers: Record<string, string>,
 ): Promise<Map<string, Record<string, unknown>>> {
 	const rows = new Map<string, Record<string, unknown>>();
 	for (const detailPath of OPENAI_COMPAT_DETAIL_PATHS) {
 		if (detailPath === modelsPath) continue;
-		const opts = { url: `${base}${detailPath}`, timeoutMs: ctx.httpTimeoutMs } as const;
+		const opts = { url: `${base}${detailPath}`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
 		const result = await (ctx.signal
 			? probeJson<OpenAIModelsResponse>({ ...opts, signal: ctx.signal })
 			: probeJson<OpenAIModelsResponse>(opts));
@@ -60,13 +75,14 @@ export async function probeOpenAIModelCatalog(
 	base: string,
 	ctx: ProbeContext,
 	modelsPath = "/v1/models",
+	headers: Record<string, string> = bearerHeaders(ctx),
 ): Promise<OpenAIModelCatalogProbe> {
-	const opts = { url: `${base}${modelsPath}`, timeoutMs: ctx.httpTimeoutMs } as const;
+	const opts = { url: `${base}${modelsPath}`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
 	const result = await (ctx.signal
 		? probeJson<OpenAIModelsResponse>({ ...opts, signal: ctx.signal })
 		: probeJson<OpenAIModelsResponse>(opts));
 	if (!result.ok || !result.data?.data) return { models: [], modelCapabilities: {}, modelStates: {} };
-	const detail = await probeModelDetailRows(base, ctx, modelsPath);
+	const detail = await probeModelDetailRows(base, ctx, modelsPath, headers);
 	const models: string[] = [];
 	const modelCapabilities: Record<string, Partial<CapabilityFlags>> = {};
 	const modelStates: Record<string, ProbeModelStatus> = {};

package/src/domains/providers/runtimes/protocol/anthropic-compat.ts

@@ -49,6 +49,11 @@ function synthesizeAnthropicCompatModel(input: AnthropicCompatSynthesisInput): M
 export function makeAnthropicCompatRuntime(spec: AnthropicCompatSpec): RuntimeDescriptor {
 	const messagesPath = spec.messagesPath ?? "/v1/messages";
 	const modelsPath = spec.modelsPath ?? "/v1/models";
+	const headers = (target: TargetDescriptor, ctx: ProbeContext): Record<string, string> => ({
+		"anthropic-version": "2023-06-01",
+		...(ctx.authToken ? { "x-api-key": ctx.authToken } : {}),
+		...target.auth?.headers,
+	});
 	return {
 		id: spec.id,
 		displayName: spec.displayName,
@@ -61,12 +66,12 @@ export function makeAnthropicCompatRuntime(spec: AnthropicCompatSpec): RuntimeDe
 		async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
 			const base = targetBaseUrl(target);
 			if (!base) return { ok: false, error: "target has no url" };
-			return probeUrl(`${base}${messagesPath}`, ctx, "HEAD");
+			return probeUrl(`${base}${messagesPath}`, ctx, "HEAD", headers(target, ctx));
 		},
 		async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
 			const base = targetBaseUrl(target);
 			if (!base) return [];
-			return probeOpenAIModels(base, ctx, modelsPath);
+			return probeOpenAIModels(base, ctx, modelsPath, headers(target, ctx));
 		},
 		synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
 			return synthesizeAnthropicCompatModel({

package/src/domains/providers/runtimes/protocol/openai-compat.ts

@@ -61,6 +61,10 @@ export function makeOpenAICompatRuntime(spec: OpenAICompatSpec): RuntimeDescript
 	// root and a target naming the `/v1` mount point has to be reduced to it. An
 	// `asIs` spec sends the URL verbatim, so it keeps whatever the user typed.
 	const probeBase = asIs ? targetBaseUrl : targetRootUrl;
+	const headers = (target: TargetDescriptor, ctx: ProbeContext): Record<string, string> => ({
+		...(ctx.authToken ? { Authorization: `Bearer ${ctx.authToken}` } : {}),
+		...target.auth?.headers,
+	});
 	return {
 		id: spec.id,
 		displayName: spec.displayName,
@@ -72,9 +76,9 @@ export function makeOpenAICompatRuntime(spec: OpenAICompatSpec): RuntimeDescript
 		async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
 			const base = probeBase(target);
 			if (!base) return { ok: false, error: "target has no url" };
-			const health = await probeUrl(`${base}${healthPath}`, ctx);
+			const health = await probeUrl(`${base}${healthPath}`, ctx, "GET", headers(target, ctx));
 			if (!health.ok) return health;
-			const catalog = await probeOpenAIModelCatalog(base, ctx, modelsPath);
+			const catalog = await probeOpenAIModelCatalog(base, ctx, modelsPath, headers(target, ctx));
 			const result: ProbeResult = { ...health };
 			if (catalog.models.length > 0) result.models = catalog.models;
 			if (Object.keys(catalog.modelStates).length > 0) result.modelStates = catalog.modelStates;
@@ -92,19 +96,21 @@ export function makeOpenAICompatRuntime(spec: OpenAICompatSpec): RuntimeDescript
 		async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
 			const base = probeBase(target);
 			if (!base) return [];
-			return probeOpenAIModels(base, ctx, modelsPath);
+			return probeOpenAIModels(base, ctx, modelsPath, headers(target, ctx));
 		},
 		async probeReasoning(target: TargetDescriptor, modelId: string, ctx: ProbeContext): Promise<ReasoningProbeResult> {
 			const base = probeBase(target);
 			if (!base) return { reasoning: false, latencyMs: 0, error: "target has no url" };
 			const apiKeyEnv = target.auth?.apiKeyEnvVar;
-			const apiKey = apiKeyEnv && ctx.credentialsPresent.has(apiKeyEnv) ? process.env[apiKeyEnv] : undefined;
+			const apiKey =
+				ctx.authToken ?? (apiKeyEnv && ctx.credentialsPresent.has(apiKeyEnv) ? process.env[apiKeyEnv] : undefined);
 			const probeOpts: Parameters<typeof probeOpenAICompatReasoning>[0] = {
 				baseUrl: base,
 				modelId,
 				timeoutMs: Math.max(ctx.httpTimeoutMs, 8000),
 			};
 			if (apiKey) probeOpts.apiKey = apiKey;
+			if (target.auth?.headers) probeOpts.headers = target.auth.headers;
 			if (ctx.signal) probeOpts.signal = ctx.signal;
 			return probeOpenAICompatReasoning(probeOpts);
 		},

package/src/domains/resources/skills/promotion.ts

@@ -109,6 +109,8 @@ export function scorePromotionEntry(userText: string, entry: MarketplaceSkill):
 
 /**
  * The uninstalled marketplace entries that match the request, best first.
+ * Authored trigger hits precede token fallbacks, even when incidental
+ * description overlap ties or exceeds the trigger's numeric score.
  * `excludedNames` carries installed skills plus every decline scope the
  * caller tracks; the matcher itself is stateless.
  */
@@ -123,7 +125,12 @@ export function matchMarketplaceSkills(
 		const match = scorePromotionEntry(userText, entry);
 		if (match) matches.push(match);
 	}
-	return matches.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+	return matches.sort(
+		(a, b) =>
+			Number(b.matchedTrigger !== undefined) - Number(a.matchedTrigger !== undefined) ||
+			b.score - a.score ||
+			a.entry.name.localeCompare(b.entry.name),
+	);
 }
 
 /**

package/src/domains/safety/action-classifier.ts

@@ -210,7 +210,16 @@ function extractWritePath(tool: string, args: Record<string, unknown> | undefine
 	return tool === ToolNames.Artifact ? artifactDefaultPath(args?.kind) : null;
 }
 
+/** Shared by classification and registry exposure; an empty body still sends data. */
+export function webFetchIsOutward(args: Record<string, unknown> | undefined): boolean {
+	const method = typeof args?.method === "string" && args.method.length > 0 ? args.method.toUpperCase() : "GET";
+	return (method !== "GET" && method !== "HEAD") || args?.body !== undefined;
+}
+
 export function classify(call: ClassifierCall): Classification {
+	if (call.tool === ToolNames.WebFetch && webFetchIsOutward(call.args)) {
+		return { actionClass: "write", reasons: ["web-fetch:outward"] };
+	}
 	const base = baseClassify(call.tool);
 	if (base === null) {
 		return { actionClass: "unknown", reasons: [`unknown tool: ${call.tool}`] };