@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/cli/validate-model.ts

@@ -1,7 +1,25 @@
+/**
+ * What a target advertised when it was asked, for runtimes with no static
+ * catalog. `models` is the id list the probe returned and `resident` the
+ * subset the server reports as loaded, when it reports load state at all.
+ */
+export interface LiveModelInventory {
+	targetId: string;
+	url?: string | undefined;
+	models: ReadonlyArray<string>;
+	resident: ReadonlyArray<string>;
+}
+
 export interface ValidateModelInput {
 	runtimeId: string;
 	modelId: string;
 	knownModels: ReadonlyArray<string>;
+	/**
+	 * The live list, when one was fetched. It is consulted only when the static
+	 * catalog is empty, so the catalog stays the authority for cloud runtimes
+	 * and the probe becomes the authority where there is nothing else.
+	 */
+	live?: LiveModelInventory | undefined;
 	force: boolean;
 }
 
@@ -9,9 +27,30 @@ export type ValidateModelResult =
 	| { ok: true; warning?: string }
 	| { ok: false; reason: string; knownModels: ReadonlyArray<string> };
 
+const SAMPLE_SIZE = 10;
+
+function sample(models: ReadonlyArray<string>): string {
+	const shown = models.slice(0, SAMPLE_SIZE).join(", ");
+	return models.length > SAMPLE_SIZE ? `${shown}, …` : shown;
+}
+
+function describeLiveTarget(live: LiveModelInventory): string {
+	return live.url ? `target '${live.targetId}' at ${live.url}` : `target '${live.targetId}'`;
+}
+
+/** The refusal `configure` prints for a model the live target does not advertise. */
+export function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
+	const resident = live.resident.length > 0 ? live.resident.join(", ") : "none";
+	return (
+		`${describeLiveTarget(live)} does not advertise model '${modelId}'. ` +
+		`Advertised (${live.models.length}): ${sample(live.models)}. Resident instances: ${resident}. ` +
+		"Pass one of the advertised ids with --model, or --force to save a model the target cannot serve."
+	);
+}
+
 export function validateModelChoice(input: ValidateModelInput): ValidateModelResult {
-	const { runtimeId, modelId, knownModels, force } = input;
-	if (knownModels.length === 0) return { ok: true };
+	const { runtimeId, modelId, knownModels, live, force } = input;
+	if (knownModels.length === 0) return validateAgainstLive(modelId, live, force);
 	if (knownModels.includes(modelId)) return { ok: true };
 	if (force) {
 		return {
@@ -19,10 +58,26 @@ export function validateModelChoice(input: ValidateModelInput): ValidateModelRes
 			warning: `model '${modelId}' not in ${runtimeId} catalog (use without --force to reject)`,
 		};
 	}
-	const sample = knownModels.slice(0, 10).join(", ");
 	return {
 		ok: false,
-		reason: `model '${modelId}' not in ${runtimeId} catalog. Known: ${sample}. Use --force to skip validation.`,
-		knownModels: knownModels.slice(0, 10),
+		reason: `model '${modelId}' not in ${runtimeId} catalog. Known: ${sample(knownModels)}. Use --force to skip validation.`,
+		knownModels: knownModels.slice(0, SAMPLE_SIZE),
 	};
 }
+
+/**
+ * With no catalog, the live list is the only evidence there is. An empty
+ * catalog used to be an early `ok` on its own, which is how a placeholder id
+ * was written next to the very list that ruled it out.
+ */
+function validateAgainstLive(
+	modelId: string,
+	live: LiveModelInventory | undefined,
+	force: boolean,
+): ValidateModelResult {
+	if (!live || live.models.length === 0) return { ok: true };
+	if (live.models.includes(modelId)) return { ok: true };
+	const reason = formatUnadvertisedModelReason(modelId, live);
+	if (force) return { ok: true, warning: `${reason.replace(/ Pass one of.*$/u, "")} Saved anyway because of --force.` };
+	return { ok: false, reason, knownModels: live.models.slice(0, SAMPLE_SIZE) };
+}

package/src/core/bus-events.ts

@@ -51,6 +51,8 @@ export const BusChannels = {
 	ToolBudgetExceeded: "safety.toolBudgetExceeded",
 	ProviderHealth: "provider.health",
 	RuntimeNotice: "runtime.notice",
+	ResidencyMutation: "residency.mutation",
+	DispatchScopeNotice: "dispatch.scopeNotice",
 	DispatchEnqueued: "dispatch.enqueued",
 	DispatchStarted: "dispatch.started",
 	DispatchProgress: "dispatch.progress",
@@ -63,6 +65,7 @@ export const BusChannels = {
 	ContextWarning: "context.warning",
 	ContextPruned: "context.pruned",
 	ContextRecalled: "context.recalled",
+	MemoryStepCompleted: "memory.stepCompleted",
 	AgentStatusChanged: "agent.status.changed",
 	RunAborted: "run.aborted",
 	BudgetAlert: "budget.alert",
@@ -99,6 +102,28 @@ export interface RuntimeNoticePayload {
 	detail?: Record<string, number | string | boolean>;
 }
 
+/**
+ * One completed proactive-memory model step, published on
+ * {@link BusChannels.MemoryStepCompleted}. It carries the endpoint the step
+ * called and nothing about what the step decided: the only consumer is the
+ * turn context, which stamps an expected-cold reason when a step ran between
+ * turns on the endpoint the chat target streams against.
+ */
+export interface MemoryStepCompletedPayload {
+	endpointKey: string;
+	targetId: string;
+}
+
+/** A successful model load or eviction on one residency-managed endpoint. */
+export interface ResidencyMutationPayload {
+	targetKey: string;
+	targetId: string;
+	runtimeId: string;
+	model: string;
+	operation: "load" | "evict";
+	at: number;
+}
+
 /**
  * Window-resolution warning published on {@link BusChannels.ContextWarning}.
  * Emitted on transitions only: `warning` carries the text when a warning
@@ -108,8 +133,31 @@ export interface ContextWarningPayload {
 	warning: string | null;
 }
 
+/** A dispatch path-scope decision that must remain visible in the operator transcript. */
+export type DispatchScopeNoticePayload =
+	| {
+			code: "typed_scope_replaced_inferred_paths";
+			level: "warning";
+			agentId: string;
+			omittedPaths: ReadonlyArray<string>;
+			message: string;
+	  }
+	| {
+			code: "legacy_scope_inferred" | "legacy_scope_empty";
+			level: "warning";
+			agentId: string;
+			paths: ReadonlyArray<{
+				path: string;
+				policy: "working-context" | "write-boundary";
+				provenance: "declared" | "derived" | "inferred";
+				source: "intent.read_roots" | "intent.write_roots" | "intent.relevant_paths" | "writeRoots" | "task" | "briefing";
+				confidence: "certain" | "high" | "medium" | "low";
+			}>;
+			message: string;
+	  };
+
 export type ContextActivityKind = "context-init" | "context-clear" | "context-refresh" | "context-wiki" | "compaction";
-export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "done";
+export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "compact" | "done";
 export type ContextActivityStatus = "started" | "running" | "completed" | "failed";
 
 /** Structured progress for context operations. Interactive renders this as a live context island. */
@@ -481,6 +529,8 @@ export interface DispatchRunIdentity {
 	wireModelId: string;
 	runtimeId: string;
 	runtimeKind: RunKind;
+	/** Canonical inference scheduler and its resolved request-slot bound. */
+	endpoint?: { key: string; label: string; limit: number } | undefined;
 	/** Admitted invocation budget provenance for native workers. */
 	budget?: RunToolBudgetEnvelope | undefined;
 	/** Fleet node id the run was placed on; absent renders as the local node. */
@@ -737,6 +787,8 @@ export type BusPayloadMap = {
 	[BusChannels.ToolBudgetExceeded]: ToolBudgetExceededPayload;
 	[BusChannels.ProviderHealth]: ProviderHealthPayload;
 	[BusChannels.RuntimeNotice]: RuntimeNoticePayload;
+	[BusChannels.ResidencyMutation]: ResidencyMutationPayload;
+	[BusChannels.DispatchScopeNotice]: DispatchScopeNoticePayload;
 	[BusChannels.DispatchEnqueued]: DispatchEnqueuedPayload;
 	[BusChannels.DispatchStarted]: DispatchStartedPayload;
 	[BusChannels.DispatchProgress]: DispatchProgressPayload;
@@ -749,6 +801,7 @@ export type BusPayloadMap = {
 	[BusChannels.ContextWarning]: ContextWarningPayload;
 	[BusChannels.ContextPruned]: ContextPrunedPayload;
 	[BusChannels.ContextRecalled]: ContextRecalledPayload;
+	[BusChannels.MemoryStepCompleted]: MemoryStepCompletedPayload;
 	[BusChannels.AgentStatusChanged]: AgentStatusChangedPayload;
 	[BusChannels.RunAborted]: RunAbortedPayload;
 	[BusChannels.BudgetAlert]: BudgetAlertPayload;

package/src/core/cache-telemetry.ts

@@ -0,0 +1,42 @@
+/** Cache classification for one backend completion call. */
+export type BackendCacheVerdict = "hot" | "partial" | "cold" | "small";
+
+/** Backend timing source that directly reports local prefill work. */
+export type BackendTimingsSource = "llamacpp-timings" | "lmstudio-timings";
+
+/** Normalized prefill and prediction timings reported by the serving backend. */
+export interface BackendCompletionTimings {
+	promptTokens: number;
+	cachedTokens: number | null;
+	predictedTokens: number;
+	promptMs: number;
+	predictedMs: number;
+	source: BackendTimingsSource;
+}
+
+/** Per-session call counts grouped by backend cache verdict. */
+export interface CacheVerdictCounts {
+	hot: number;
+	partial: number;
+	cold: number;
+	small: number;
+}
+
+export function emptyCacheVerdictCounts(): CacheVerdictCounts {
+	return { hot: 0, partial: 0, cold: 0, small: 0 };
+}
+
+/** Return newly evaluated prefill tokens when the backend reports cache reads. */
+export function uncachedPrefillTokens(backend: BackendCompletionTimings | null | undefined): number | null {
+	if (backend === null || backend === undefined || backend.cachedTokens === null) return null;
+	if (
+		!Number.isFinite(backend.promptTokens) ||
+		backend.promptTokens < 0 ||
+		!Number.isFinite(backend.cachedTokens) ||
+		backend.cachedTokens < 0 ||
+		backend.cachedTokens > backend.promptTokens
+	) {
+		return null;
+	}
+	return backend.promptTokens - backend.cachedTokens;
+}

package/src/core/commit-attribution.ts

@@ -16,7 +16,7 @@ export const CLIO_COMMIT_TRAILERS = {
 } as const;
 
 export interface CommitReceiptEvidence {
-	version: 19;
+	version: 20;
 	algorithm: "sha256";
 	digest: string;
 	/** The receipt was checked against its run-ledger envelope. */
@@ -58,7 +58,7 @@ const KNOWN_CLIO_TRAILERS = new Set(
 );
 
 function isClioTrailer(key: string): boolean {
-	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v19/sha256:");
+	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v20/sha256:");
 }
 
 /**
@@ -87,7 +87,7 @@ function trailerBlockStart(lines: ReadonlyArray<string>): number | null {
 
 function receiptTrailer(receipt: CommitReceiptEvidence | undefined): string | null {
 	if (
-		receipt?.version !== 19 ||
+		receipt?.version !== 20 ||
 		receipt.algorithm !== "sha256" ||
 		receipt.integrityValid !== true ||
 		receipt.directlyRelevant !== true ||
@@ -95,7 +95,7 @@ function receiptTrailer(receipt: CommitReceiptEvidence | undefined): string | nu
 	) {
 		return null;
 	}
-	return `Clio-Evidence: receipt-v19/sha256:${receipt.digest}`;
+	return `Clio-Evidence: receipt-v20/sha256:${receipt.digest}`;
 }
 
 /**

package/src/core/config.ts

@@ -521,6 +521,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
 	const runtime = "runtime" in value ? expectString(issues, `${path}.runtime`, value.runtime) : undefined;
@@ -566,6 +567,10 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
 	}
+	if ("maxConcurrentRequests" in value) {
+		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
+		if (v !== undefined) target.maxConcurrentRequests = v;
+	}
 	return target;
 }
 
@@ -1004,6 +1009,7 @@ const TOP_LEVEL_KEYS = [
 	"keybindings",
 	"compaction",
 	"context",
+	"prewarm",
 	"retry",
 	"guardrails",
 ] as const;
@@ -1589,6 +1595,18 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		}
 	}
 
+	if ("prewarm" in raw) {
+		if (!isPlainObject(raw.prewarm)) {
+			issues.add("prewarm", `expected a map, got ${describe(raw.prewarm)}`);
+		} else {
+			issues.unknownKeys("prewarm", raw.prewarm, ["enabled"]);
+			if ("enabled" in raw.prewarm) {
+				const v = expectBoolean(issues, "prewarm.enabled", raw.prewarm.enabled);
+				if (v !== undefined) settings.prewarm.enabled = v;
+			}
+		}
+	}
+
 	if ("retry" in raw) {
 		if (!isPlainObject(raw.retry)) {
 			issues.add("retry", `expected a map, got ${describe(raw.retry)}`);

package/src/core/defaults.ts

@@ -151,6 +151,21 @@ export interface WorkingSetSettings {
 	minEvictableTokens: number;
 }
 
+/**
+ * Prompt pre-warm settings (`prewarm`). On a local server prefill is the cost,
+ * and the prefix the next turn will send is fully known before the operator
+ * types anything: at session start, after a resume rebuilds the message array,
+ * and after a compaction settles. Clio sends that prefix to the backend right
+ * then so the slot's prefix cache already holds it when the real turn arrives.
+ *
+ *   - enabled: master switch. The feature is off on every tier but
+ *     `local-native` whatever this says, and off for workers and headless runs,
+ *     because it buys latency for an operator watching a local server.
+ */
+export interface PrewarmSettings {
+	enabled: boolean;
+}
+
 /**
  * Transient provider retry controls for the interactive chat loop. These are
  * intentionally small and mirror the session retry helper defaults. Dispatched
@@ -354,11 +369,15 @@ export const DEFAULT_SETTINGS = {
 			everyNTools: 10,
 			windowSteps: 8,
 			maxTokens: 400,
-			// A memory step runs detached from the turn that triggered it, so a
-			// generous deadline costs no interactive latency. Measured steps on a
-			// small local route ranged past two minutes, and a deadline shorter than
-			// the model discards finished work as a timeout.
-			timeoutMs: 180_000,
+			// A memory step runs detached from the turn that triggered it, but it
+			// runs on a real inference endpoint that the operator's own turns and
+			// dispatched workers also queue against. The operator's ledger over 14
+			// days recorded 60 llm-tier steps spending 1,666 seconds of model time
+			// for 6 injections, with one step holding a local server for 102.5
+			// seconds to answer nothing. The deadline is what a turn boundary can
+			// actually wait for; a step that runs past it is recorded as timed out
+			// rather than spending the remaining minutes unobserved.
+			timeoutMs: 30_000,
 		},
 	},
 	watchdog: { enabled: false } as WatchdogSettings,
@@ -444,6 +463,9 @@ export const DEFAULT_SETTINGS = {
 	context: {
 		workingSet: DEFAULT_WORKING_SET_SETTINGS,
 	},
+	prewarm: {
+		enabled: true,
+	} as PrewarmSettings,
 	retry: {
 		enabled: true,
 		maxRetries: 3,
@@ -539,7 +561,7 @@ memory:
     everyNTools: 10
     windowSteps: 8
     maxTokens: 400
-    timeoutMs: 180000
+    timeoutMs: 30000
 
 # Opt-in turn-end watchdog. When enabled, a turn that changed the tree is
 # reviewed by one read-only verifier run briefed with the turn's coalesced diff
@@ -751,6 +773,14 @@ context:
     protectLastTurns: 6
     minEvictableTokens: 200
 
+# Prompt pre-warm. At session start, after a resume rebuilds the message array,
+# and after a compaction settles, Clio sends the prefix the next turn would send
+# (minus your text) so a local server has already prefilled it when you press
+# Enter. Local-native targets only, interactive sessions only, and never while a
+# turn or a dispatch is running.
+prewarm:
+  enabled: true
+
 # Transient provider/stream retry controls for interactive chat.
 # Retryable errors include overloads, rate limits, 5xx responses, network
 # resets, and timeouts. Context overflow uses compaction recovery instead.

package/src/core/endpoint-key.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical identity of an OpenAI-compatible inference endpoint: normalized
+ * HTTP scheme, lower-cased host, normalized port, and normalized base path with
+ * a conventional terminal `/v1` mount stripped. Credentials, query, and
+ * fragment do not participate. Host aliases are not resolved, so
+ * `localhost` and `127.0.0.1` stay distinct. Shared by dispatch capacity and
+ * residency locking so both speak the same key for one server.
+ */
+export function canonicalEndpointUrl(raw: string | null | undefined): string | null {
+	if (!raw?.trim()) return null;
+	try {
+		const url = new URL(raw.trim().replace(/^ws:/u, "http:").replace(/^wss:/u, "https:"));
+		url.protocol = url.protocol.toLowerCase();
+		if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+		url.hostname = url.hostname.toLowerCase();
+		url.username = "";
+		url.password = "";
+		url.hash = "";
+		url.search = "";
+		let path = url.pathname.replace(/\/{2,}/gu, "/").replace(/\/$/u, "");
+		if (path.endsWith("/v1")) path = path.slice(0, -3);
+		url.pathname = path || "/";
+		return url.toString().replace(/\/$/u, "");
+	} catch {
+		return null;
+	}
+}

package/src/core/path-boundary.ts

@@ -0,0 +1,100 @@
+import path from "node:path";
+
+export const PATH_BOUNDARY_MAX_ENTRIES = 32;
+
+export type PathBoundary = ReadonlyArray<string>;
+
+type PathBoundaryErrorCode = "empty" | "separator" | "glob" | "absolute" | "parent" | "dot";
+
+export class PathBoundaryError extends Error {
+	readonly code: PathBoundaryErrorCode;
+
+	constructor(code: PathBoundaryErrorCode, message: string) {
+		super(message);
+		this.name = "PathBoundaryError";
+		this.code = code;
+	}
+}
+
+const GLOB_CHARACTERS = /[*?[\]{}]/u;
+
+/** Normalize one repository-relative boundary entry. */
+export function normalizePathBoundaryEntry(entry: string): string {
+	const raw = entry.trim();
+	if (raw.length === 0) throw new PathBoundaryError("empty", "write boundary: entry must be a non-empty path");
+	if (raw.includes("\\")) {
+		throw new PathBoundaryError("separator", `write boundary: entry '${entry}' must use '/' separators`);
+	}
+	if (GLOB_CHARACTERS.test(raw)) {
+		throw new PathBoundaryError("glob", `write boundary: entry '${entry}' looks like a glob, which v1 does not support`);
+	}
+	if (raw.startsWith("/") || /^[A-Za-z]:/u.test(raw)) {
+		throw new PathBoundaryError("absolute", `write boundary: entry '${entry}' must be repository-relative, not absolute`);
+	}
+	const subtree = raw.endsWith("/");
+	const segments = raw.split("/").filter((segment) => segment.length > 0);
+	if (segments.length === 0) {
+		throw new PathBoundaryError("empty", `write boundary: entry '${entry}' must name a path inside the repository`);
+	}
+	for (const segment of segments) {
+		if (segment === "..") {
+			throw new PathBoundaryError("parent", `write boundary: entry '${entry}' must not contain '..'`);
+		}
+		if (segment === ".") {
+			throw new PathBoundaryError("dot", `write boundary: entry '${entry}' must not contain '.' segments`);
+		}
+	}
+	const joined = segments.join("/");
+	return subtree ? `${joined}/` : joined;
+}
+
+/** Normalize, deduplicate, and sort a boundary declaration. */
+export function normalizePathBoundary(entries: ReadonlyArray<string>): string[] {
+	if (entries.length > PATH_BOUNDARY_MAX_ENTRIES) {
+		throw new Error(`write boundary: at most ${PATH_BOUNDARY_MAX_ENTRIES} entries may be declared`);
+	}
+	return [...new Set(entries.map(normalizePathBoundaryEntry))].sort();
+}
+
+function toPosixBoundaryPath(value: string): string {
+	return value.split("\\").join("/");
+}
+
+function isDirectoryPathBoundary(entry: string): boolean {
+	return toPosixBoundaryPath(entry).endsWith("/");
+}
+
+/** Convert a path to the subtree form spoken by the boundary grammar. */
+export function asDirectoryPathBoundary(entry: string): string {
+	const normalized = toPosixBoundaryPath(entry);
+	return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
+/** Resolve a repository-relative boundary while retaining exact or subtree meaning. */
+export function resolvePathBoundary(cwd: string, entry: string): string {
+	const directory = isDirectoryPathBoundary(entry);
+	const withoutMarker = directory ? entry.slice(0, -1) : entry;
+	const resolved = toPosixBoundaryPath(path.resolve(cwd, withoutMarker));
+	return directory ? asDirectoryPathBoundary(resolved) : resolved;
+}
+
+/** Whether one boundary entry contains another exact path or subtree. */
+export function pathBoundaryEntryCovers(outer: string, inner: string): boolean {
+	const normalizedOuter = toPosixBoundaryPath(outer);
+	const normalizedInner = toPosixBoundaryPath(inner);
+	return normalizedOuter.endsWith("/")
+		? normalizedInner.startsWith(normalizedOuter)
+		: !normalizedInner.endsWith("/") && normalizedInner === normalizedOuter;
+}
+
+/** Whether any entry in a boundary contains the candidate. */
+export function pathBoundaryCovers(boundary: PathBoundary, candidate: string): boolean {
+	return boundary.some((entry) => pathBoundaryEntryCovers(entry, candidate));
+}
+
+/** Whether two boundary declarations share any possible path. */
+export function pathBoundariesOverlap(left: PathBoundary, right: PathBoundary): boolean {
+	return left.some((entry) =>
+		right.some((other) => pathBoundaryEntryCovers(entry, other) || pathBoundaryEntryCovers(other, entry)),
+	);
+}

package/src/core/residency-target-key.ts

@@ -0,0 +1,25 @@
+import { canonicalEndpointUrl } from "./endpoint-key.js";
+
+/** Runtime families whose model residency Clio can actively mutate. */
+export type ResidencyRuntimeId = "llamacpp" | "lmstudio" | "ollama-native";
+
+const RESIDENCY_RUNTIME_IDS: ReadonlySet<string> = new Set<ResidencyRuntimeId>([
+	"llamacpp",
+	"lmstudio",
+	"ollama-native",
+]);
+
+export function residencyTargetKey(runtimeId: ResidencyRuntimeId, baseUrl: string): string;
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null;
+/** Stable key for one residency-managed server endpoint: its canonical URL. */
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null {
+	if (!RESIDENCY_RUNTIME_IDS.has(runtimeId) || typeof baseUrl !== "string") return null;
+	// The key is the canonical endpoint itself, without a runtime prefix, so the
+	// residency lock and dispatch capacity name one server the same way (#250).
+	// A base url the canonical form refuses, such as one written without a
+	// scheme, still gets a key: callers store this in `ResidencyAdapter.targetKey`,
+	// which is a `string`, and dispatch capacity has no key for that target
+	// either, so there is nothing to agree with and nothing to gain by dropping
+	// the lock the reconciler serializes on.
+	return canonicalEndpointUrl(baseUrl) ?? baseUrl;
+}

package/src/core/response-schema.ts

@@ -11,11 +11,45 @@ export const RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES = 64 * 1024;
  * `schema` key, and returns HTTP 200 with unconstrained JSON, so widening this
  * to the api family would convert a clean refusal into a silent
  * non-enforcement. lmstudio declares `structuredOutputs: "json-schema"`
- * truthfully and is still excluded here, because Clio has no dialect for its
- * transport. Widen this only together with a dialect for the runtime added.
+ * truthfully and is still excluded here, because the worker seam has no
+ * dialect for its transport. Widen this only together with a dialect for the
+ * runtime added; {@link responseSchemaDialectFor} is where the out-of-turn
+ * seam did exactly that (issue #223).
  */
 export const RESPONSE_SCHEMA_RUNTIME_ID = "llamacpp";
 
+/** The runtime that takes the standard OpenAI `json_schema` response format. */
+export const OPENAI_SCHEMA_RUNTIME_ID = "lmstudio";
+
+/**
+ * How a runtime spells a JSON-schema response constraint on the wire.
+ *
+ * `llamacpp-json-object` is llama-server's own `response_format: { type:
+ * "json_object", schema }`, which it compiles into a sampler grammar.
+ * `openai-json-schema` is the standard `response_format: { type:
+ * "json_schema", json_schema: { name, strict, schema } }` that LM Studio
+ * implements.
+ */
+export type ResponseSchemaDialect = "llamacpp-json-object" | "openai-json-schema";
+
+/**
+ * The dialect this runtime takes, or null when Clio has none for it and the
+ * request has to go unconstrained.
+ *
+ * Deliberately a name check, for the reason {@link RESPONSE_SCHEMA_RUNTIME_ID}
+ * gives: a generic OpenAI-compatible gateway answers HTTP 200 to a spelling it
+ * does not implement and returns unconstrained JSON, so a capability flag would
+ * turn a known non-enforcement into a silent one. This is the out-of-turn
+ * seam's table; the worker seam keeps the narrower
+ * {@link runtimeSpeaksResponseSchemaDialect} check, because a worker that
+ * cannot enforce a contract must refuse admission rather than degrade.
+ */
+export function responseSchemaDialectFor(runtimeId: string): ResponseSchemaDialect | null {
+	if (runtimeId === RESPONSE_SCHEMA_RUNTIME_ID) return "llamacpp-json-object";
+	if (runtimeId === OPENAI_SCHEMA_RUNTIME_ID) return "openai-json-schema";
+	return null;
+}
+
 /** Whether this runtime speaks the dialect above. Transport shape, not capability. */
 export function runtimeSpeaksResponseSchemaDialect(runtime: { id: string; kind: string; apiFamily: string }): boolean {
 	return (

package/src/domains/agents/extension.ts

@@ -1,12 +1,9 @@
-import path from "node:path";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
-import { resolvePackageRoot } from "../../core/package-root.js";
-import { clioConfigDir } from "../../core/xdg.js";
 import { assertAgentIdNamespace } from "../config/agent-namespace.js";
 import type { ConfigContract } from "../config/contract.js";
 import type { AgentsContract } from "./contract.js";
 import type { AgentRecipe } from "./recipe.js";
-import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "./registry.js";
+import { type AgentRecipeDiagnostic, discoverAgentRecipes } from "./registry.js";
 import { type AgentSpec, normalizeAgentSpec } from "./spec.js";
 
 export function createAgentsBundle(_context: DomainContext): DomainBundle<AgentsContract> {
@@ -15,14 +12,8 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
 
 	function discover(): void {
-		const builtinDir = path.join(resolvePackageRoot(), "src", "domains", "agents", "builtins");
-		const userDir = path.join(clioConfigDir(), "agents");
-		const projectDir = path.join(process.cwd(), ".clio-coder", "agents");
 		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
-		const builtin = loadRecipesFromDir({ dir: builtinDir, source: "builtin" }, nextDiagnostics);
-		const user = loadRecipesFromDir({ dir: userDir, source: "user" }, nextDiagnostics);
-		const project = loadRecipesFromDir({ dir: projectDir, source: "project" }, nextDiagnostics);
-		const merged = mergeRecipes(builtin, user, project);
+		const merged = discoverAgentRecipes(process.cwd(), nextDiagnostics);
 		const config = _context.getContract<ConfigContract>("config");
 		assertAgentIdNamespace(merged, config?.get()?.delegation?.agents ?? []);
 		recipes = merged;