@iowarp/clio-coder 0.4.0 → 0.4.2

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

@@ -1,42 +1,40 @@
 ---
 id: operating.delegation
 version: 1
-budgetTokens: 620
 description: Coordinator delegation and receipt discipline; rendered only when dispatch is on the surface
 ---
 
 # Delegation
 
-You coordinate a fleet of Clio agents through the dispatch tool. You
-plan, route, and synthesize work across turns.
-Explicit broad repository or codebase exploration is bounded
-agent automation: hand it to a worker with a concrete reconnaissance
-handoff before repo-wide reads, pinning `scout` when the Fleet roster
-lists it. Use dispatch for other bounded fleet work with a clear
-handoff. A sealed run
-receipt is the durable record for delegated work. Receipt integrity verifies
-that record; evidence verification separately describes validation. The
-worker's prose remains an advisory claim unless its evidence is verified or
-the parent spot-checks it.
-A successful reconnaissance receipt is an index. Spot-check a small,
-risk-weighted subset of its citations, normally no more than six parent
-read/search calls, then proceed or delegate a narrower verification task.
-Spot-check delegated claims before repeating them: re-read any cited
-file:line location, and re-run or inspect the named validation before
-repeating a "tests pass" claim.
-Parent spot-checking is not independent specialist confirmation. Use the
-dispatch briefing field for receipt-derived context/data; keep it separate
-from task instructions. Collect detached runs before final synthesis.
-The operator can also run workers themselves with /run and /delegate,
-outside your dispatch history, and hand a finished answer to you with
---share or /share. Such an answer arrives as operator text headed
-`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
-and its run id names a sealed receipt you can read. Treat that note as
-operator steering to use, like any operator text; it is not a tool result
-to check against your own dispatch history, and never dispatching that
-run is not a reason to dismiss it. Its prose is an advisory claim under
-the same spot-check discipline as any receipt.
-Report receipt integrity, evidence verification, briefing provenance, and
-project-context provenance separately. Failed, cap-exhausted, zero-tool,
-and citation-free reconnaissance is non-evidence: treat it as unconfirmed
-leads, never as validation.
+You coordinate Clio workers through the dispatch tool. Before your first
+edit, count the independent file-scoped changes the request asks for.
+Two or more, or any repository-wide exploration: dispatch, and do not
+edit those files yourself. One narrow change: do it yourself.
+For two or more changes, one dispatch call carries them all as `tasks`,
+one task per change, each naming its file in `intent`, with `agent`
+"coder" and `mode` "parallel". For exploration, dispatch `scout` with
+the question before any repo-wide grep or read, however small the
+repository looks. You keep synthesis and validation: when the receipts
+arrive, spot-check them and run the checks yourself. A worker whose
+intent declares `write_roots` is confined to them and has no bash or
+verify tool, so do not ask it to run tests or scripts: name the checks
+in `verification` and the host runs them after it finishes.
+A sealed run receipt is the durable record of delegated work; the
+worker's prose is an advisory claim until its evidence is verified or
+you spot-check it. Spot-check a small, risk-weighted subset of a
+reconnaissance receipt's citations (normally at most six read or search
+calls), and re-read any cited file:line and re-run or inspect the named
+validation before repeating a "tests pass" claim. Failed, cap-exhausted,
+zero-tool, or citation-free reconnaissance is unconfirmed leads, never
+validation.
+Put receipt-derived context in the dispatch briefing field, separate
+from task instructions. Collect detached runs before final synthesis,
+and report receipt integrity, evidence verification, briefing
+provenance, and project-context provenance as separate facts. Never
+narrate or summarize a worker you did not dispatch; if you cannot
+dispatch, say so and name the reason.
+A note headed `[worker result] <agent> · run <id> · <outcome> · shared
+by the operator` is operator text: a worker the operator ran with /run
+or /delegate and shared with --share or /share. Use it like any operator
+steering, read its receipt by run id, and apply the same spot-check
+discipline; not having dispatched it is no reason to dismiss it.

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

@@ -1,26 +1,19 @@
 ---
 id: operating.skills
 version: 1
-budgetTokens: 260
 description: Coordinator skill suggestion discipline; rendered only when context is on the surface
 ---
 
 # Skills
 
-Skills package proven workflows. Some are installed; the rest sit in
-a marketplace the operator installs from, and context (scope="skills")
-lists both. Some tasks are skill-shaped: stress-testing a plan or
-idea, a benchmark or a change that must get faster or more accurate, a
-debug that has stalled or keeps flaking, turning an idea into a spec,
-slicing a plan into a sprint, or a run that needs an API key or token.
-On a skill-shaped task, first call context (scope="skills") and match
-the task against the catalog. Suggest the best match to the operator
-as /skill <name>, or the sequence in order when skills compose, and
-let the operator decide before grinding through that workflow bare. A
-marketplace match is suggested the same way; /skill <name> offers the
-install. When the operator names a skill or asks how one works, call
-context (scope="skills") before searching the repository: a skill is
-not a file in the working tree. Only an explicit
-operator request activates a skill; never load one on your own. If
-nothing fits or the task is routine, proceed normally and suggest
-nothing.
+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.

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

@@ -1,16 +1,9 @@
 ---
 id: operating.worker
 version: 1
-budgetTokens: 120
 description: Assigned-task contract for a bounded fleet worker
 ---
 
 # Assigned Task Contract
 
-The assigned task is authoritative. Role guidance is a persona, not a replacement task.
-
-Do not invent a different task, source tree, file path, or implementation plan.
-
-If the assigned task asks for an exact response, a direct answer, or no tool use, answer it directly without tool calls.
-
-Use tools only when necessary for the assigned task and admitted by the worker tool contract.
+The assigned task is authoritative; role guidance is a persona, not a replacement. Do not invent a different task, source tree, file path, or implementation plan.

package/src/domains/providers/extension.ts

@@ -88,7 +88,7 @@ function positiveWindow(value: unknown): number | undefined {
  * `n_ctx: 0` still discovers the window it did publish, instead of silently
  * falling back to the runtime descriptor's placeholder.
  */
-export function capabilitiesFor(
+function capabilitiesFor(
 	desc: RuntimeDescriptor,
 	target: TargetDescriptor,
 	probe: ProbeMerge,
@@ -173,7 +173,7 @@ export interface ProbeMerge {
  * `cache`, while health and availability (decided by the caller from `probe`)
  * reflect the failure. Only a successful probe replaces the catalog.
  */
-export function mergeProbeResult(
+function mergeProbeResult(
 	desc: RuntimeDescriptor,
 	target: TargetDescriptor,
 	probe: ProbeResult | null,
@@ -224,7 +224,7 @@ export function mergeProbeResult(
  * Returns the reason when the default is not served, null when it is or when
  * there is no live evidence either way.
  */
-export function unservedDefaultModelReason(
+function unservedDefaultModelReason(
 	desc: Pick<RuntimeDescriptor, "id">,
 	target: Pick<TargetDescriptor, "defaultModel">,
 	merge: Pick<ProbeMerge, "discoveredModels" | "discoveredModelsSource" | "discoveredModelStates">,
@@ -396,7 +396,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		}
 		if (probeResult.ok && options?.reasoning !== false && typeof desc.probeReasoning === "function") {
 			const settings = readConfig();
-			const orchestratorTarget = settings.orchestrator.target === target.id ? settings.orchestrator.model : null;
+			const orchestratorTarget = settings.chat.target === target.id ? settings.chat.model : null;
 			const candidateModelId = orchestratorTarget ?? target.defaultModel ?? null;
 			if (candidateModelId) {
 				try {
@@ -482,7 +482,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			registerClioOAuthProviders();
 			registerBuiltinRuntimes(registry);
 			const settings = readConfig();
-			setGlobalDefaultMaxOutputTokens(settings.defaults.maxTokens);
+			setGlobalDefaultMaxOutputTokens(settings.chat.maxOutputTokens);
 			await loadPluginRuntimes(registry, settings);
 			await probeAll();
 			const config = context.getContract<ConfigContract>("config");

package/src/domains/providers/index.ts

@@ -161,7 +161,7 @@ export {
 	VALID_THINKING_LEVELS,
 } from "./types/capability-flags.js";
 export { type ContextWindowSlots, formatContextWindowSlots } from "./types/context-window-slots.js";
-export { type CostProvenance, normalizeCostProvenance } from "./types/cost-provenance.js";
+export { type CostProvenance, normalizeCostProvenance, resolveCostProvenance } from "./types/cost-provenance.js";
 export type { KnowledgeBase, KnowledgeBaseEntry, KnowledgeBaseHit } from "./types/knowledge-base.js";
 export type {
 	ProbeContext,

package/src/domains/providers/knowledge-base-path.ts

@@ -72,7 +72,7 @@ function envOverlayDirs(): string[] {
 		.filter((entry) => entry.length > 0);
 }
 
-export function resolveProviderModelCatalogDirs(
+function resolveProviderModelCatalogDirs(
 	importMetaUrl: string,
 	options: { cwd?: string } = {},
 ): ProviderModelCatalogDirs {

package/src/domains/providers/model-runtime-capabilities.ts

@@ -1,3 +1,4 @@
+import { warnLegacyNaming } from "../../core/naming-compat.js";
 import type { Api, Model } from "../../engine/types.js";
 import { getCatalogModelForRuntime } from "./catalog.js";
 import type { ProvidersContract, TargetStatus } from "./contract.js";
@@ -35,7 +36,7 @@ export interface AppliedThinking {
 	mechanism: ThinkingMechanism;
 	effort?: string;
 	budgetTokens?: number;
-	chatTemplateKwargs?: Record<string, boolean>;
+	chatTemplateKwargs?: Record<string, boolean | string | number>;
 	noticeKind: AppliedThinkingNoticeKind;
 	notice: string;
 }
@@ -52,7 +53,20 @@ export interface ResolvedRequestCapability {
 	reasoningEffort?: string;
 	budgetTokens?: number;
 	budgetEnforcement: ThinkingBudgetEnforcement;
-	chatTemplateKwargs?: Record<string, boolean | string>;
+	chatTemplateKwargs?: Record<string, boolean | string | number>;
+	/**
+	 * Family-declared chat-template kwargs the runtime cannot carry. LM Studio
+	 * ignores `chat_template_kwargs` for every family measured, so the keys are
+	 * named here for the resolution diagnostics instead of riding in
+	 * `chatTemplateKwargs` only to be deleted at the wire.
+	 */
+	undeliverableChatTemplateKwargs?: UndeliverableChatTemplateKwargs;
+}
+
+export interface UndeliverableChatTemplateKwargs {
+	keys: string[];
+	/** True when the family entry itself marks the block `lmstudio: unsupported`. */
+	declaredUnsupported: boolean;
 }
 
 export interface ResolvedResponseCapability {
@@ -111,10 +125,19 @@ function capabilityHints(input: {
 }
 
 interface ClioRuntimeMetadata {
+	clioCoder?: {
+		targetId?: string;
+		runtimeId?: string;
+		lifecycle?: "user-managed" | "clio-coder-managed";
+		gateway?: boolean;
+		family?: string;
+		quirks?: LocalModelQuirks;
+	};
+	/** Released in-memory metadata name accepted at plugin/runtime read boundaries. */
 	clio?: {
 		targetId?: string;
 		runtimeId?: string;
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		family?: string;
 		quirks?: LocalModelQuirks;
@@ -325,14 +348,15 @@ function supportedEffortLevels(
 ): ReadonlyArray<ThinkingLevel> {
 	if (harmony) return HARMONY_LEVELS;
 	const efforts = quirks?.thinking?.effortByLevel;
-	if (!efforts) return baseLevels;
+	const byLevelValues = (quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs)?.byLevel?.values;
+	if (!efforts && !byLevelValues) return baseLevels;
 	const out: ThinkingLevel[] = [];
 	if (baseLevels.includes("off")) out.push("off");
-	if (efforts.minimal !== undefined) out.push("minimal");
-	if (efforts.low !== undefined) out.push("low");
-	if (efforts.medium !== undefined) out.push("medium");
-	if (efforts.high !== undefined) out.push("high");
-	if (efforts.xhigh !== undefined) out.push("xhigh");
+	if (efforts?.minimal !== undefined || byLevelValues?.minimal !== undefined) out.push("minimal");
+	if (efforts?.low !== undefined || byLevelValues?.low !== undefined) out.push("low");
+	if (efforts?.medium !== undefined || byLevelValues?.medium !== undefined) out.push("medium");
+	if (efforts?.high !== undefined || byLevelValues?.high !== undefined) out.push("high");
+	if (efforts?.xhigh !== undefined || byLevelValues?.xhigh !== undefined) out.push("xhigh");
 	return out.length > 0 ? out : baseLevels;
 }
 
@@ -515,27 +539,71 @@ function resolveThinkingCapability(
 }
 
 /**
- * Runtimes whose OpenAI-compatible surface reads the on-off thinking control
- * from `reasoning_effort` rather than `chat_template_kwargs.enable_thinking`.
- * Measured against the live fleet on 2026-08-11 with
- * `nvidia-nemotron-3.5-lightning-30b-a3b`: LM Studio suppressed reasoning
- * entirely for `reasoning_effort: "none"` and ignored `enable_thinking: false`,
- * while llama.cpp did the reverse. Sending the wrong spelling reads as "no
- * preference" to the server, so the model keeps reasoning at every dial.
+ * Runtimes whose OpenAI-compatible surface ignores `chat_template_kwargs`
+ * and reads every thinking control from `reasoning_effort`. Measured against
+ * dynamo (LM Studio) on 2026-08-11 with `nvidia-nemotron-3.5-lightning-30b-a3b`
+ * and again on 2026-09-02 across three mechanisms: `enable_thinking: false`
+ * left 26 reasoning tokens on qwen3.8-27b (effort-levels), 52 on
+ * gemma-4-26b-a4b-it (on-off) and 105 on nemotron-3.5-lightning (on-off),
+ * while `reasoning_effort: "none"` produced 0 on each; llama.cpp does the
+ * reverse. Sending the wrong spelling reads as "no preference" to the
+ * server, so the model keeps reasoning at every dial. The same runtime drops
+ * a family's own kwargs (#267) for the same reason, so those are reported as
+ * undeliverable rather than merged into the request (#268).
  */
-const REASONING_EFFORT_ON_OFF_RUNTIMES: ReadonlySet<string> = new Set(["lmstudio"]);
+const REASONING_EFFORT_ONLY_RUNTIMES: ReadonlySet<string> = new Set(["lmstudio"]);
 
 /** `none` is LM Studio's documented off value; on-off models have no finer dial than `low`. */
 function onOffReasoningEffort(thinkingActive: boolean): string {
 	return thinkingActive ? "low" : "none";
 }
 
+function resolveFamilyChatTemplateKwargs(
+	quirks: LocalModelQuirks | undefined,
+	effectiveLevel: ThinkingLevel,
+	configuredLevel: ThinkingLevel,
+): Record<string, boolean | string | number> | undefined {
+	const block = quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs;
+	if (!block) return undefined;
+	const out: Record<string, boolean | string | number> = {};
+	if (block.static) {
+		for (const [k, v] of Object.entries(block.static)) {
+			out[k] = v;
+		}
+	}
+	if (block.byLevel) {
+		const byLevel = block.byLevel;
+		const val = byLevel.values[effectiveLevel] ?? byLevel.values[configuredLevel];
+		if (val !== undefined) {
+			out[byLevel.key] = val;
+		}
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function familyKwargsDeclaredUnsupported(quirks: LocalModelQuirks | undefined, runtimeId: string): boolean {
+	if (runtimeId !== "lmstudio") return false;
+	const block = quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs;
+	return block?.lmstudio === "unsupported" || block?.byLevel?.lmstudio === "unsupported";
+}
+
 function resolveRequestCapability(
 	thinking: ResolvedThinkingCapability,
 	parser: ResponseParserKind,
 	runtimeId: string,
+	quirks?: LocalModelQuirks,
 ): ResolvedRequestCapability {
 	const request: ResolvedRequestCapability = { budgetEnforcement: thinking.budgetEnforcement };
+	const effortOnly = REASONING_EFFORT_ONLY_RUNTIMES.has(runtimeId);
+	const familyKwargs = resolveFamilyChatTemplateKwargs(quirks, thinking.effectiveLevel, thinking.configuredLevel);
+	if (familyKwargs && effortOnly) {
+		request.undeliverableChatTemplateKwargs = {
+			keys: Object.keys(familyKwargs),
+			declaredUnsupported: familyKwargsDeclaredUnsupported(quirks, runtimeId),
+		};
+	} else if (familyKwargs) {
+		request.chatTemplateKwargs = { ...familyKwargs };
+	}
 	if (thinking.mechanism === "effort-levels" && thinking.effort) {
 		request.reasoningEffort = thinking.effort;
 	}
@@ -546,15 +614,21 @@ function resolveRequestCapability(
 		request.budgetTokens = thinking.budgetTokens;
 	}
 	if (thinking.mechanism === "on-off" && thinking.chatTemplateKwargs) {
-		request.chatTemplateKwargs = { ...thinking.chatTemplateKwargs };
-		if (REASONING_EFFORT_ON_OFF_RUNTIMES.has(runtimeId)) {
-			request.reasoningEffort = onOffReasoningEffort(thinking.thinkingActive);
-		}
+		request.chatTemplateKwargs = { ...(request.chatTemplateKwargs ?? {}), ...thinking.chatTemplateKwargs };
 	}
 	if (parser === "harmony" && thinking.effort) {
 		request.reasoningEffort = thinking.effort;
 		request.chatTemplateKwargs = { ...(request.chatTemplateKwargs ?? {}), reasoning_effort: thinking.effort };
 	}
+	// Every mechanism that means "off" has to reach an effort-only runtime as
+	// reasoning_effort "none": the template flag above is what llama.cpp reads
+	// and what LM Studio drops. An interactive session with thinking "off" had
+	// spent 37k reasoning tokens before the effort-levels case reached the
+	// wire, and on-off and budget-tokens families reasoned on the same way.
+	if (effortOnly && thinking.mechanism !== "none" && thinking.mechanism !== "always-on") {
+		if (!thinking.thinkingActive) request.reasoningEffort = onOffReasoningEffort(false);
+		else if (thinking.mechanism === "on-off") request.reasoningEffort = onOffReasoningEffort(true);
+	}
 	return request;
 }
 
@@ -573,7 +647,7 @@ export function resolveModelRuntimeCapabilities(
 		family,
 		capabilities: input.capabilities,
 		thinking,
-		request: resolveRequestCapability(thinking, parser, input.runtimeId),
+		request: resolveRequestCapability(thinking, parser, input.runtimeId, quirks),
 		response: {
 			parser,
 			stripTokenizerSentinels: true,
@@ -691,7 +765,9 @@ export function resolveModelRuntimeCapabilitiesForModel<TApi extends Api>(
 	model: Model<TApi>,
 	configuredThinkingLevel?: ThinkingLevel,
 ): ResolvedModelRuntimeCapabilities {
-	const metadata = (model as Model<TApi> & ClioRuntimeMetadata).clio;
+	const runtimeModel = model as Model<TApi> & ClioRuntimeMetadata;
+	if (runtimeModel.clio !== undefined) warnLegacyNaming("model.clio", "model.clioCoder");
+	const metadata = runtimeModel.clioCoder ?? runtimeModel.clio;
 	const caps = capabilitiesFromModel(model as Model<Api> & ClioRuntimeMetadata);
 	return resolveModelRuntimeCapabilities({
 		targetId: metadata?.targetId ?? null,

package/src/domains/providers/models/cloud-models/alcf.yaml

@@ -1,7 +1,7 @@
 # ALCF (Argonne) inference-gateway model knowledge base.
 #
 # GPT-OSS models served through ALCF are already covered by the existing
-# openai-gpt-oss family in local-models/clio-local-coding-targets.yaml.
+# openai-gpt-oss family in local-models/clio-coder-local-coding-targets.yaml.
 
 - family: meta-llama-4-maverick
   matchPatterns: