@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/providers/model-discovery.ts

@@ -1,5 +1,6 @@
 import type { TargetStatus } from "./contract.js";
 import { listKnownModelsForRuntime } from "./support.js";
+import type { ContextWindowSlots } from "./types/context-window-slots.js";
 
 export type ProviderModelSource = "configured" | "live" | "catalog" | "default";
 
@@ -45,6 +46,14 @@ export function loadedContextWindowForModel(
 	return typeof reported === "number" && Number.isFinite(reported) && reported > 0 ? reported : null;
 }
 
+/** How the server splits its KV budget for this model, when the probe saw it split. */
+export function contextSlotsForModel(
+	status: DiscoveryStatus | null | undefined,
+	modelId: string,
+): ContextWindowSlots | null {
+	return status?.discoveredModelStates?.[modelId]?.contextSlots ?? null;
+}
+
 /**
  * Residency as one view, so the planner and the "not resident" notice cannot
  * disagree about the same model. A reported loaded window settles it whatever

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

@@ -5,7 +5,7 @@ import { getCatalogModelForRuntime, resolveCostProvenance } from "./catalog.js";
 import type { ProvidersContract, TargetStatus } from "./contract.js";
 import { isDispatchEligibleRuntime, isOrchestratorEligibleRuntime, isTargetEligibleRuntime } from "./eligibility.js";
 import { probeCapabilitiesForModel, resolveModelCapabilities } from "./model-capabilities.js";
-import { hasLiveModelCatalog, loadedContextWindowForModel } from "./model-discovery.js";
+import { contextSlotsForModel, hasLiveModelCatalog, loadedContextWindowForModel } from "./model-discovery.js";
 import {
 	type ReasoningClass,
 	type ResolvedModelRuntimeCapabilities,
@@ -14,6 +14,7 @@ import {
 	resolveTargetRuntimeCapabilities,
 } from "./model-runtime-capabilities.js";
 import type { CapabilityFlags, ThinkingLevel } from "./types/capability-flags.js";
+import type { ContextWindowSlots } from "./types/context-window-slots.js";
 import type { CostProvenance } from "./types/cost-provenance.js";
 import type { KnowledgeBase } from "./types/knowledge-base.js";
 import type {
@@ -52,6 +53,12 @@ export interface ContextWindowDetails {
 	effectiveContextWindow: number;
 	/** Where `effectiveContextWindow` came from. */
 	contextWindowSource: ContextWindowSource;
+	/**
+	 * Present when the probed window is a per-request share of the server's
+	 * KV budget (llama.cpp `--ctx-size` over `--parallel` slots), so the
+	 * operator surfaces can render `196,608 (786,432 / 4 slots)`.
+	 */
+	contextWindowSlots: ContextWindowSlots | null;
 	/** The window is below what this kind of work wants. An actionable degradation. */
 	warning: string | null;
 	/** The window is a placeholder rather than something the target reported. */
@@ -406,6 +413,8 @@ export function resolveRuntimeTarget(
 		providers.knowledgeBase,
 		probedContextWindow,
 		loadedContextWindow,
+		undefined,
+		contextSlotsForModel(status, wireModelId),
 	);
 	capabilities.contextWindow = contextWindowDetails.effectiveContextWindow;
 	if (contextWindowDetails.warning) {
@@ -513,6 +522,7 @@ export function refineRuntimeTargetWithModelHints(
 		// hand the planner the declared window back on the first refinement.
 		target.contextWindowDetails.loadedContextWindow,
 		modelHintContextWindow,
+		target.contextWindowDetails.contextWindowSlots,
 	);
 	capabilities.contextWindow = contextWindowDetails.effectiveContextWindow;
 
@@ -582,6 +592,21 @@ export function runtimeResolutionWarnings(diagnostics: ReadonlyArray<RuntimeReso
 	return diagnostics.filter((entry) => entry.severity === "warning").map((entry) => entry.message);
 }
 
+/**
+ * The warnings a surface that prints its own thinking-clamp line should
+ * announce. `thinking-coerced` and `thinking-<kind>` are the two halves of
+ * that one line, so when the resolved thinking carries a notice they are
+ * dropped here: an always-on model printed three lines saying one thing
+ * (issue #191). With no notice, a bare coercion is still worth a line.
+ */
+export function runtimeResolutionWarningsBesideThinkingNotice(
+	diagnostics: ReadonlyArray<RuntimeResolutionDiagnostic>,
+	thinkingNotice: string,
+): string[] {
+	if (thinkingNotice.trim().length === 0) return runtimeResolutionWarnings(diagnostics);
+	return runtimeResolutionWarnings(diagnostics.filter((entry) => !entry.code.startsWith("thinking-")));
+}
+
 /**
  * Minimum context Clio is built for, applied to every tier rather than only to
  * local-native. A hosted target that reports less than this is as unable to
@@ -623,6 +648,7 @@ export function resolveContextWindowDetails(
 	probedContextWindow: number | null,
 	loadedContextWindow: number | null = null,
 	modelHintContextWindow?: number,
+	probedContextSlots: ContextWindowSlots | null = null,
 ): ContextWindowDetails {
 	const catalogModel = getCatalogModelForRuntime(runtime.id, wireModelId);
 	const kbHit = knowledgeBase?.lookup(wireModelId) ?? null;
@@ -707,6 +733,16 @@ export function resolveContextWindowDetails(
 			`Run 'clio-coder targets --probe' to read the real one.`;
 	}
 
+	// The split explains the probed number and nothing else: once an override
+	// or a loaded window decides the figure, `786,432 / 4 slots` no longer
+	// describes it.
+	const contextWindowSlots =
+		source === "probe" &&
+		probedContextSlots !== null &&
+		Math.floor(probedContextSlots.totalContextSize / probedContextSlots.slots) === effective
+			? probedContextSlots
+			: null;
+
 	return {
 		declaredContextWindow,
 		probedContextWindow,
@@ -714,6 +750,7 @@ export function resolveContextWindowDetails(
 		desiredContextWindow: desired,
 		effectiveContextWindow: effective,
 		contextWindowSource: source,
+		contextWindowSlots,
 		warning,
 		provenanceNotice,
 	};

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

@@ -1,5 +1,6 @@
 import { probeHttp, probeJson } from "../../probe/http.js";
 import type { CapabilityFlags } from "../../types/capability-flags.js";
+import { type ContextWindowSlots, formatContextWindowSlots } from "../../types/context-window-slots.js";
 import type { ProbeContext, ProbeModelStatus, ProbeResult } from "../../types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../../types/target-descriptor.js";
 
@@ -88,7 +89,15 @@ export async function probeOpenAIModelCatalog(
 			// A reported loaded context is itself the residency answer: nothing
 			// serves a window for a model it has not loaded.
 			(loadedContext !== undefined ? { state: "loaded" as const } : undefined);
-		if (state) modelStates[row.id] = loadedContext === undefined ? state : { ...state, contextLength: loadedContext };
+		// The slot split rides on the load-state record because it is the same
+		// kind of fact: how this server is serving this model. A row with no
+		// recognized state still gets one, as `unknown`, so the split is kept
+		// without claiming residency the server did not report.
+		const contextSlots = contextSlotsFromEntry(row) ?? (detailRow ? contextSlotsFromEntry(detailRow) : undefined);
+		const withSlots = contextSlots ? { ...(state ?? { state: "unknown" as const }), contextSlots } : state;
+		if (withSlots) {
+			modelStates[row.id] = loadedContext === undefined ? withSlots : { ...withSlots, contextLength: loadedContext };
+		}
 	}
 	return { models, modelCapabilities, modelStates };
 }
@@ -159,7 +168,15 @@ function normalizeModelState(raw: string | undefined): ProbeModelStatus["state"]
 	if (!value) return undefined;
 	if (value === "loaded" || value === "ready" || value === "running" || value === "active") return "loaded";
 	if (value === "loading" || value === "pending" || value === "queued" || value === "starting") return "loading";
-	if (value === "unloaded" || value === "not-loaded" || value === "idle" || value === "stopped") return "unloaded";
+	if (
+		value === "unloaded" ||
+		value === "not-loaded" ||
+		value === "idle" ||
+		value === "sleeping" ||
+		value === "stopped"
+	) {
+		return "unloaded";
+	}
 	if (value === "failed" || value === "error" || value === "errored") return "failed";
 	if (value === "unknown") return "unknown";
 	return undefined;
@@ -203,12 +220,16 @@ function statusArgsFromEntry(row: Record<string, unknown>): string[] {
 	return argsFromStatus(status);
 }
 
+function contextSlotsFromEntry(row: Record<string, unknown>): ContextWindowSlots | undefined {
+	return llamaCppRequestContextWindow(parseLlamaCppServerFlags(statusArgsFromEntry(row)))?.slots;
+}
+
 function capabilitiesFromOpenAIModelEntry(row: Record<string, unknown>): Partial<CapabilityFlags> {
 	const caps: Partial<CapabilityFlags> = {};
 	const meta = nestedRecord(row, "meta");
 	const flags = parseLlamaCppServerFlags(statusArgsFromEntry(row));
 	const contextWindow =
-		positiveNumber(flags.contextSize) ??
+		llamaCppRequestContextWindow(flags)?.contextWindow ??
 		firstPositiveNumber(row, [
 			// What is actually loaded outranks what the model could support: a
 			// model served at 8k out of a possible 262k has an 8k window today,
@@ -310,10 +331,43 @@ export interface LlamaCppServerFlags {
 	topK?: number;
 	nGpuLayers?: number;
 	parallel?: number;
+	/** `--kv-unified` / `-kvu` true, `--no-kv-unified` false, absent when neither was given. */
+	kvUnified?: boolean;
 	mmproj?: string;
 	chatTemplateKwargs?: string;
 }
 
+export interface LlamaCppRequestContextWindow {
+	/** What one request can use. */
+	contextWindow: number;
+	/** Present when `contextWindow` is a quotient of the server's total. */
+	slots?: ContextWindowSlots;
+}
+
+/**
+ * The window one request actually gets from a llama.cpp server.
+ *
+ * `--ctx-size` is the total KV budget of the process. Without `--kv-unified`
+ * the server splits it evenly across `--parallel` slots, so a router started
+ * with `--ctx-size 786432 --parallel 4 --no-kv-unified` admits 196,608 tokens
+ * per request while reporting 786,432 as its context size. Reading the total
+ * as the window armed autocompact at a number the server would never admit
+ * and walked a long session into a hard context failure with the meter at
+ * 25% (issue #187). With `--kv-unified` every slot shares one sequence and
+ * the total is the window.
+ */
+export function llamaCppRequestContextWindow(flags: LlamaCppServerFlags): LlamaCppRequestContextWindow | undefined {
+	const total = positiveNumber(flags.contextSize);
+	if (total === undefined) return undefined;
+	const parallel = positiveNumber(flags.parallel);
+	if (parallel === undefined || parallel <= 1 || flags.kvUnified === true) return { contextWindow: Math.floor(total) };
+	const slots = Math.floor(parallel);
+	return {
+		contextWindow: Math.floor(total / slots),
+		slots: { totalContextSize: Math.floor(total), slots },
+	};
+}
+
 export interface LlamaCppStatusEnrichment {
 	discoveredCapabilities?: Partial<CapabilityFlags>;
 	modelId?: string;
@@ -329,22 +383,37 @@ function argsFromStatus(status: unknown): string[] {
 	return [];
 }
 
-function valueAfter(args: ReadonlyArray<string>, flag: string): string | undefined {
-	const index = args.indexOf(flag);
-	if (index < 0) return undefined;
-	const value = args[index + 1];
-	return value && !value.startsWith("--") ? value : undefined;
+/** `-1` is a value (`--reasoning-budget -1`); `-np` and `--jinja` are flags. */
+function looksLikeFlag(token: string): boolean {
+	return token.startsWith("-") && Number.isNaN(Number(token));
 }
 
-function numberFlag(args: ReadonlyArray<string>, flag: string): number | undefined {
-	const value = valueAfter(args, flag);
+/**
+ * The value after the first of `flags` present, or undefined. A token that
+ * reads as the next flag is not a value, which is how boolean flags read as
+ * present-without-value. Short spellings (`-c`, `-np`) come after the long
+ * one so the long form wins when both are given.
+ */
+function valueAfter(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): string | undefined {
+	for (const flag of flags) {
+		const index = args.indexOf(flag);
+		if (index < 0) continue;
+		const value = args[index + 1];
+		return value && !looksLikeFlag(value) ? value : undefined;
+	}
+	return undefined;
+}
+
+function numberFlag(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): number | undefined {
+	const value = valueAfter(args, ...flags);
 	if (value === undefined) return undefined;
 	const parsed = Number(value);
 	return Number.isFinite(parsed) ? parsed : undefined;
 }
 
-function booleanFlag(args: ReadonlyArray<string>, flag: string): boolean | undefined {
-	if (!args.includes(flag)) return undefined;
+function booleanFlag(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): boolean | undefined {
+	const flag = flags.find((candidate) => args.includes(candidate));
+	if (flag === undefined) return undefined;
 	const value = valueAfter(args, flag);
 	if (value === undefined) return true;
 	const normalized = value.toLowerCase();
@@ -353,9 +422,9 @@ function booleanFlag(args: ReadonlyArray<string>, flag: string): boolean | undef
 	return undefined;
 }
 
-function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
+export function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
 	const flags: LlamaCppServerFlags = {};
-	const ctxSize = numberFlag(args, "--ctx-size");
+	const ctxSize = numberFlag(args, "--ctx-size", "-c");
 	if (ctxSize !== undefined) flags.contextSize = ctxSize;
 	const maxTokens = numberFlag(args, "--n-predict");
 	if (maxTokens !== undefined) flags.maxTokens = maxTokens;
@@ -375,8 +444,14 @@ function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFl
 	if (topK !== undefined) flags.topK = topK;
 	const nGpuLayers = numberFlag(args, "--n-gpu-layers");
 	if (nGpuLayers !== undefined) flags.nGpuLayers = nGpuLayers;
-	const parallel = numberFlag(args, "--parallel");
+	const parallel = numberFlag(args, "--parallel", "-np");
 	if (parallel !== undefined) flags.parallel = parallel;
+	// The negative spelling is its own flag, and the last one given wins, which
+	// is how llama.cpp itself resolves a repeated boolean option.
+	const kvUnifiedAt = Math.max(args.lastIndexOf("--kv-unified"), args.lastIndexOf("-kvu"));
+	const noKvUnifiedAt = args.lastIndexOf("--no-kv-unified");
+	if (noKvUnifiedAt > kvUnifiedAt) flags.kvUnified = false;
+	else if (kvUnifiedAt >= 0) flags.kvUnified = booleanFlag(args, "--kv-unified", "-kvu") ?? true;
 	const cacheTypeK = valueAfter(args, "--cache-type-k");
 	if (cacheTypeK) flags.cacheTypeK = cacheTypeK;
 	const cacheTypeV = valueAfter(args, "--cache-type-v");
@@ -418,7 +493,8 @@ export async function probeLlamaCppModelStatus(
 	if (args.length === 0) return { notes: statusNotes(selected.id, selected.status) };
 	const flags = parseLlamaCppServerFlags(args);
 	const caps: Partial<CapabilityFlags> = {};
-	if (flags.contextSize !== undefined && flags.contextSize > 0) caps.contextWindow = flags.contextSize;
+	const window = llamaCppRequestContextWindow(flags);
+	if (window !== undefined) caps.contextWindow = window.contextWindow;
 	if (flags.maxTokens !== undefined && flags.maxTokens > 0) caps.maxTokens = flags.maxTokens;
 	if (flags.reasoning === true || flags.reasoningBudget !== undefined) caps.reasoning = true;
 	if (flags.mmproj) caps.vision = true;
@@ -426,6 +502,11 @@ export async function probeLlamaCppModelStatus(
 	const enrichment: LlamaCppStatusEnrichment = { modelId: selected.id, serverFlags: flags };
 	if (Object.keys(caps).length > 0) enrichment.discoveredCapabilities = caps;
 	const notes = statusNotes(selected.id, selected.status);
+	if (window?.slots) {
+		notes.push(
+			`${selected.id} context window ${formatContextWindowSlots(window.contextWindow, window.slots)}: --ctx-size is split across --parallel slots without --kv-unified`,
+		);
+	}
 	if (notes.length > 0) enrichment.notes = notes;
 	return enrichment;
 }

package/src/domains/providers/types/context-window-slots.ts

@@ -0,0 +1,18 @@
+/**
+ * A server that shares one KV budget across request slots serves each request
+ * a quotient of it. llama.cpp splits `--ctx-size` evenly across `--parallel`
+ * slots unless `--kv-unified`, so a router started with `--ctx-size 786432
+ * --parallel 4 --no-kv-unified` admits 196,608 tokens per request. The total
+ * and the slot count are kept beside the quotient so the operator surfaces can
+ * say where the number came from.
+ */
+export interface ContextWindowSlots {
+	totalContextSize: number;
+	slots: number;
+}
+
+/** `196,608 (786,432 / 4 slots)`: the per-request window with its derivation. */
+export function formatContextWindowSlots(contextWindow: number, slots: ContextWindowSlots): string {
+	const format = (n: number): string => Math.round(n).toLocaleString("en-US");
+	return `${format(contextWindow)} (${format(slots.totalContextSize)} / ${slots.slots} slots)`;
+}

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

@@ -1,6 +1,6 @@
 import type { Api, Model } from "../../../engine/types.js";
-
 import type { CapabilityFlags } from "./capability-flags.js";
+import type { ContextWindowSlots } from "./context-window-slots.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";
@@ -61,6 +61,8 @@ export type ProbeModelLoadState = "loaded" | "loading" | "unloaded" | "failed" |
 export interface ProbeModelStatus {
 	state: ProbeModelLoadState;
 	detail?: string;
+	/** The per-request window is `totalContextSize / slots`; absent when the server does not split. */
+	contextSlots?: ContextWindowSlots;
 	/**
 	 * 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,

package/src/domains/resources/index.ts

@@ -18,6 +18,24 @@ export function createResourcesDomainModule(options: ResourceLoaderOptions = {})
 export type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
 export { resolveResourceCollisions } from "./collision.js";
 export type { ResourceList, ResourcesContract } from "./contract.js";
+export {
+	classifyLibraryRequirements,
+	confirmLibraryRemote,
+	discoverLibrary,
+	installLibraryPlan,
+	type LibraryCommandRunner,
+	type LibraryDiscoveryResult,
+	type LibraryEntry,
+	type LibraryInstallPlan,
+	type LibraryRequirementStatus,
+	libraryEntryInstalled,
+	libraryEntryPin,
+	libraryEntryRef,
+	libraryInstallPath,
+	planLibraryInstall,
+	resolveLibraryRequirements,
+	syncLibrary,
+} from "./library.js";
 export { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
 export { ResourcesManifest } from "./manifest.js";
 export {
@@ -61,6 +79,8 @@ export {
 	discoverMarketplaceSkills,
 	getMarketplaceSkills,
 	installSkill,
+	type LibraryEntryKind,
+	type LibraryRequirementRef,
 	MARKETPLACE_UNCONFIGURED,
 	type MarketplaceDiscoveryResult,
 	type MarketplaceSkill,