@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/domains/providers/runtimes/local-native/lmstudio.ts

@@ -0,0 +1,241 @@
+import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
+import type { Api, Model } from "../../../../engine/types.js";
+import type { CapabilityFlags, ThinkingLevel } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { ProbeContext, ProbeModelStatus, ProbeResult, RuntimeDescriptor } from "../../types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+import {
+	foldLmStudioModels,
+	greetLmStudio,
+	type LmStudioCatalog,
+	type LmStudioLoadedInstance,
+	type LmStudioModelInfo,
+	listLmStudioModels,
+	lmStudioReasoningLevels,
+	loadedContextLength,
+	parseLmStudioV1Models,
+	resolveLmStudioInstance,
+} from "../common/lmstudio-http.js";
+import { synthLocalModel, withV1 } from "../common/local-synth.js";
+
+const defaultCapabilities: CapabilityFlags = {
+	chat: true,
+	tools: true,
+	toolCallFormat: "openai",
+	structuredOutputs: "json-schema",
+	reasoning: true,
+	vision: true,
+	audio: false,
+	embeddings: false,
+	rerank: false,
+	fim: false,
+	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
+	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
+};
+
+const reasoningOptionsByTargetModel = new Map<string, ReadonlyArray<string>>();
+
+function reasoningOptionsKey(target: TargetDescriptor, modelId: string): string {
+	const url = (target.url ?? "").replace(/^ws:/u, "http:").replace(/^wss:/u, "https:").replace(/\/$/u, "");
+	return `${target.id}|${url}|${modelId}`;
+}
+
+function rememberReasoningOptions(target: TargetDescriptor, models: ReadonlyArray<LmStudioModelInfo>): void {
+	const prefix = reasoningOptionsKey(target, "");
+	for (const key of reasoningOptionsByTargetModel.keys()) {
+		if (key.startsWith(prefix)) reasoningOptionsByTargetModel.delete(key);
+	}
+	for (const model of models) {
+		if (!model.reasoningOptions) continue;
+		reasoningOptionsByTargetModel.set(reasoningOptionsKey(target, model.key), model.reasoningOptions);
+		for (const instance of model.loadedInstances) {
+			reasoningOptionsByTargetModel.set(reasoningOptionsKey(target, instance.id), model.reasoningOptions);
+		}
+	}
+}
+
+function configuredModel(target: TargetDescriptor): string | undefined {
+	const id = target.defaultModel?.trim();
+	return id && id.length > 0 ? id : undefined;
+}
+
+function resolveModel(
+	models: ReadonlyArray<LmStudioModelInfo>,
+	id: string | undefined,
+): { model: LmStudioModelInfo; instance?: LmStudioLoadedInstance } | null {
+	if (id) {
+		for (const model of models) {
+			if (model.key === id) return { model, ...(model.loadedInstances[0] ? { instance: model.loadedInstances[0] } : {}) };
+			const instance = model.loadedInstances.find((entry) => entry.id === id);
+			if (instance) return { model, instance };
+		}
+		return null;
+	}
+	const model = models.find((entry) => entry.loadedInstances.length > 0) ?? models[0];
+	return model ? { model, ...(model.loadedInstances[0] ? { instance: model.loadedInstances[0] } : {}) } : null;
+}
+
+function capabilities(model: LmStudioModelInfo, instance?: LmStudioLoadedInstance): Partial<CapabilityFlags> {
+	const out: Partial<CapabilityFlags> = {};
+	if (model.vision !== undefined) out.vision = model.vision;
+	if (model.tools !== undefined) out.tools = model.tools;
+	if (model.reasoning !== undefined) out.reasoning = model.reasoning;
+	else if (model.reasoningOptions !== undefined)
+		out.reasoning = model.reasoningOptions.some((option) => option !== "off");
+	const contextWindow = loadedContextLength(instance) ?? model.maxContextLength;
+	if (contextWindow !== undefined) out.contextWindow = contextWindow;
+	return out;
+}
+
+function statusFor(
+	model: LmStudioModelInfo,
+	instance: LmStudioLoadedInstance | undefined,
+	reasoningLevels: ReadonlyArray<ThinkingLevel>,
+): ProbeModelStatus {
+	const status: ProbeModelStatus = {
+		state: instance ? "loaded" : "unloaded",
+		key: model.key,
+		reasoningLevels,
+	};
+	if (instance) {
+		status.instanceId = instance.id;
+		status.loadConfig = instance.config;
+		const contextLength = loadedContextLength(instance);
+		if (contextLength !== undefined) status.contextLength = contextLength;
+	}
+	return status;
+}
+
+function probeFromCatalog(catalog: LmStudioCatalog, target: TargetDescriptor): ProbeResult {
+	if (!catalog.ok) {
+		return {
+			ok: false,
+			...(catalog.latencyMs !== undefined ? { latencyMs: catalog.latencyMs } : {}),
+			error: catalog.error ?? "LM Studio model listing failed",
+		};
+	}
+	const models = foldLmStudioModels(catalog.models);
+	rememberReasoningOptions(target, models);
+	const ids: string[] = [];
+	const modelCapabilities: Record<string, Partial<CapabilityFlags>> = {};
+	const modelStates: Record<string, ProbeModelStatus> = {};
+	for (const model of models) {
+		const levels = lmStudioReasoningLevels(model.reasoningOptions);
+		const keyInstance = model.loadedInstances[0];
+		modelCapabilities[model.key] = capabilities(model, keyInstance);
+		modelStates[model.key] = statusFor(model, keyInstance, levels);
+		for (const instance of model.loadedInstances) {
+			if (!ids.includes(instance.id)) ids.push(instance.id);
+			modelCapabilities[instance.id] = capabilities(model, instance);
+			const instanceStatus = statusFor(model, instance, levels);
+			modelStates[instance.id] = instanceStatus;
+			const resolution = resolveLmStudioInstance(target, models, instance.id, configuredModel(target));
+			instanceStatus.detail =
+				resolution.peerTargets.length > 0
+					? `loaded on ${target.id}; also loaded on ${resolution.peerTargets.join(", ")}`
+					: `loaded on ${target.id}`;
+		}
+		if (model.loadedInstances.length === 0) {
+			ids.push(model.key);
+			const keyStatus = modelStates[model.key];
+			if (keyStatus) keyStatus.detail = "not loaded (LM Studio will load it on first use)";
+		}
+	}
+	const selected = resolveModel(models, configuredModel(target));
+	const result: ProbeResult = {
+		ok: true,
+		models: ids,
+		modelCapabilities,
+		modelStates,
+		serverVersion:
+			catalog.tier === "0.4+"
+				? "LM Studio API 0.4+"
+				: catalog.tier === "0.3.x"
+					? "LM Studio API 0.3.x"
+					: "LM Studio OpenAI-compatible API",
+		surfaces: {
+			openaiChat: "/v1/chat/completions",
+			...(catalog.tier === "0.4+" ? { nativeV1: "/api/v1/models" } : {}),
+			...(catalog.tier === "0.3.x" ? { nativeV0: "/api/v0/models" } : {}),
+		},
+	};
+	if (catalog.latencyMs !== undefined) result.latencyMs = catalog.latencyMs;
+	if (selected) {
+		result.discoveredCapabilities = capabilities(selected.model, selected.instance);
+		result.capabilityModelId = configuredModel(target) ?? selected.model.key;
+	}
+	const loaded = models.flatMap((model) =>
+		model.loadedInstances.map((instance) => {
+			const context = loadedContextLength(instance);
+			return `${model.key} as ${instance.id}${context ? ` at ${context} tokens` : ""}`;
+		}),
+	);
+	result.notes = [
+		`LM Studio surface tier ${catalog.tier ?? "unknown"}`,
+		`Surfaces: ${Object.values(result.surfaces ?? {}).join(", ")}`,
+		...(loaded.length > 0 ? [`Loaded instances: ${loaded.join(", ")}`] : []),
+	];
+	return result;
+}
+
+export function probeResultFromV1Models(data: unknown, target: TargetDescriptor, latencyMs?: number): ProbeResult {
+	const models = parseLmStudioV1Models(data);
+	if (!models) return { ok: false, error: "LM Studio /api/v1/models response has no models array" };
+	return probeFromCatalog({ ok: true, models, tier: "0.4+", ...(latencyMs !== undefined ? { latencyMs } : {}) }, target);
+}
+
+const lmstudioRuntime: RuntimeDescriptor = {
+	id: "lmstudio",
+	aliases: ["lmstudio-native"],
+	displayName: "LM Studio",
+	kind: "http",
+	tier: "local-native",
+	apiFamily: "openai-completions",
+	auth: "api-key",
+	defaultCapabilities,
+	async probe(target, ctx): Promise<ProbeResult> {
+		const [greeting, catalog] = await Promise.all([greetLmStudio(target, ctx), listLmStudioModels(target, ctx)]);
+		if (!greeting.ok && catalog.tier !== "0.3.x") {
+			return {
+				ok: false,
+				...(greeting.latencyMs !== undefined ? { latencyMs: greeting.latencyMs } : {}),
+				error: `URL did not identify itself as LM Studio: ${greeting.error ?? "greeting missing"}`,
+			};
+		}
+		return probeFromCatalog(catalog, target);
+	},
+	async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
+		const catalog = await listLmStudioModels(target, ctx);
+		return probeFromCatalog(catalog, target).models ?? [];
+	},
+	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
+		const canonicalTarget = target.runtime === "lmstudio" ? target : { ...target, runtime: "lmstudio" };
+		const model = synthLocalModel({
+			target: canonicalTarget,
+			wireModelId,
+			kb,
+			defaultCapabilities,
+			apiFamily: "openai-completions",
+			provider: "lmstudio",
+			baseUrlForTarget: (url) => withV1(url.replace(/^ws:/u, "http:").replace(/^wss:/u, "https:")),
+		});
+		const metadata = (
+			model as Model<Api> & {
+				clio?: {
+					chatTemplateKwargsUnsupported?: boolean;
+					lmstudioReasoningOptions?: ReadonlyArray<string>;
+					lmstudioDefaultModel?: string;
+				};
+			}
+		).clio;
+		if (metadata) {
+			metadata.chatTemplateKwargsUnsupported = true;
+			if (target.defaultModel) metadata.lmstudioDefaultModel = target.defaultModel;
+			const options = reasoningOptionsByTargetModel.get(reasoningOptionsKey(canonicalTarget, wireModelId));
+			if (options) metadata.lmstudioReasoningOptions = options;
+		}
+		return model;
+	},
+};
+
+export default lmstudioRuntime;

package/src/domains/providers/support.ts

@@ -55,7 +55,7 @@ const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
 	"openai-codex": "ChatGPT Plus/Pro via Codex OAuth",
 	openrouter: "OpenRouter API",
 	"ollama-native": "Ollama native API",
-	"lmstudio-native": "LM Studio SDK + native model management",
+	lmstudio: "LM Studio chat over OpenAI-compatible REST with native REST model management",
 	llamacpp: "llama.cpp server (auto-detect surface)",
 	"anthropic-compat": "Generic Anthropic-compatible REST",
 	"openai-compat": "Generic OpenAI-compatible REST",
@@ -151,7 +151,7 @@ export function defaultModelForRuntime(runtimeId: string): string | undefined {
  * about which ids matter.
  */
 export function describeRuntimeModels(entry: ProviderSupportEntry, sample: number): string {
-	if (entry.modelSource === "catalog") return `${entry.modelHints.length} in pi-ai catalog`;
+	if (entry.modelSource === "catalog") return `${entry.modelHints.length} in catalog`;
 	if (entry.modelHints.length === 0) return "-";
 	return entry.modelHints.slice(0, sample).join(", ");
 }
@@ -206,7 +206,10 @@ export function configuredTargetsForRuntime(
 	settings: Readonly<ClioSettings>,
 	runtimeId: string,
 ): ReadonlyArray<TargetDescriptor> {
-	return settings.targets.filter((target) => target.runtime === runtimeId);
+	const canonical = getRuntimeIfRegistered(runtimeId)?.id ?? runtimeId;
+	return settings.targets.filter(
+		(target) => (getRuntimeIfRegistered(target.runtime)?.id ?? target.runtime) === canonical,
+	);
 }
 
 export function resolveProviderReference(

package/src/domains/providers/types/local-model-quirks.ts

@@ -6,11 +6,9 @@
  * into a typed shape that flows through `model.clio.quirks` at synth time.
  *
  * Field naming follows the Hugging Face / model-card terminology so the YAML
- * can be authored against the source-of-truth card. Engine adapters translate
- * these into the SDK-specific names at consumption sites:
- *   - LM Studio SDK uses `topPSampling`, `topKSampling`, `minPSampling`,
- *     `repeatPenalty`, `llamaKCacheQuantizationType`.
- *   - LM Studio's OpenAI-compat surface accepts `top_p`, `top_k`, `min_p`,
+ * can be authored against the source-of-truth card. The OpenAI adapter
+ * translates these into pi-ai sampling parameters at consumption:
+ *   - OpenAI-compatible surfaces accept `top_p`, `top_k`, `min_p`,
  *     `repeat_penalty`.
  */
 
@@ -81,7 +79,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-export function asKvCacheQuant(value: unknown): KvCacheQuant | false | undefined {
+function asKvCacheQuant(value: unknown): KvCacheQuant | false | undefined {
 	if (value === false) return false;
 	if (typeof value !== "string") return undefined;
 	return (KV_CACHE_QUANTS as ReadonlyArray<string>).includes(value) ? (value as KvCacheQuant) : undefined;
@@ -122,9 +120,9 @@ function extractSamplingProfile(raw: unknown): SamplingProfile | undefined {
 	if (topK !== undefined) out.topK = topK;
 	const minP = asPositive(raw.minP);
 	if (minP !== undefined) out.minP = minP;
-	// Catalog YAML may use either `repeatPenalty` (LM Studio SDK term) or
-	// `repetitionPenalty` (HF model-card term); accept both, prefer the SDK
-	// spelling when both are present.
+	// Catalog YAML may use either `repeatPenalty` (engine field name) or
+	// `repetitionPenalty` (HF model-card term); accept both, preferring the
+	// engine spelling when both are present.
 	const rp = asPenalty(raw.repeatPenalty) ?? asPenalty(raw.repetitionPenalty);
 	if (rp !== undefined) out.repeatPenalty = rp;
 	const pp = asPenalty(raw.presencePenalty);

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

@@ -17,7 +17,6 @@ export type RuntimeApiFamily =
 	| "bedrock-converse-stream"
 	| "google-generative-ai"
 	| "google-vertex"
-	| "lmstudio-native"
 	| "mistral-conversations"
 	| "ollama-native"
 	| "rerank-http"
@@ -53,6 +52,8 @@ export interface ProbeSurfaceMap {
 	rerank?: string;
 	completion?: string;
 	infill?: string;
+	nativeV1?: string;
+	nativeV0?: string;
 }
 
 export type ProbeModelLoadState = "loaded" | "loading" | "unloaded" | "failed" | "unknown";
@@ -76,6 +77,14 @@ export interface ProbeModelStatus {
 	 */
 	sizeVramBytes?: number;
 	sizeBytes?: number;
+	/** Downloaded model key that owns this configured id or loaded instance. */
+	key?: string;
+	/** Loaded instance id selected for this model, when one exists. */
+	instanceId?: string;
+	/** Load configuration echoed by LM Studio for the selected instance. */
+	loadConfig?: Readonly<Record<string, unknown>>;
+	/** Reasoning levels accepted by this model after LM Studio option clamping. */
+	reasoningLevels?: ReadonlyArray<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
 }
 
 export interface ProbeResult {
@@ -115,6 +124,8 @@ export interface ReasoningProbeResult {
 
 export interface RuntimeDescriptor {
 	id: string;
+	/** Deprecated or compatibility ids that resolve to this descriptor object. */
+	aliases?: ReadonlyArray<string>;
 	displayName: string;
 	kind: RuntimeKind;
 	tier?: RuntimeTier;

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

@@ -18,6 +18,27 @@ export interface TargetPricing {
 // unrenamed by rebrand decision so existing `lifecycle:` lines keep working.
 export type TargetLifecycle = "user-managed" | "clio-managed";
 
+export interface LmStudioLoadSettings {
+	contextLength?: number;
+	flashAttention?: boolean;
+	evalBatchSize?: number;
+	numExperts?: number;
+	offloadKvCacheToGpu?: boolean;
+}
+
+export type LmStudioReasoningSetting = "auto" | "off" | "on" | "low" | "medium" | "high";
+
+export interface LmStudioRequestSettings {
+	ttlSeconds?: number;
+	draftModel?: string;
+	reasoning?: LmStudioReasoningSetting;
+}
+
+export interface LmStudioTargetSettings {
+	load?: LmStudioLoadSettings;
+	request?: LmStudioRequestSettings;
+}
+
 /**
  * Persisted target specification from settings.yaml (`targets:`). It binds a
  * user-facing target id to a RuntimeDescriptor id, target URL/auth metadata,
@@ -35,4 +56,5 @@ export interface TargetDescriptor {
 	lifecycle?: TargetLifecycle;
 	gateway?: boolean;
 	pricing?: TargetPricing;
+	lmstudio?: LmStudioTargetSettings;
 }

package/src/domains/resources/contract.ts

@@ -19,7 +19,6 @@ export interface ResourcesContract extends DomainContract {
 	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
 	prompts(cwd?: string): ResourceList<PromptTemplate>;
 	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
-	themes(): ResourceList<never>;
 	resolvePath(value: string, cwd?: string): string;
 	reload(): Promise<void>;
 }

package/src/domains/resources/extension.ts

@@ -10,6 +10,7 @@ export function createResourcesBundle(
 	const config = (): ConfigContract | undefined => context.getContract<ConfigContract>("config");
 	const loader = createResourcesLoader({
 		...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+		...(options.reservedPromptNames !== undefined ? { reservedPromptNames: options.reservedPromptNames } : {}),
 		skills: () => ({
 			...skillOptions(config()?.get().skills.trustProjectCompatRoots === true, options),
 		}),
@@ -35,9 +36,6 @@ export function createResourcesBundle(
 		expandPromptTemplate(text, cwd) {
 			return loader.expandPromptTemplate(text, cwd);
 		},
-		themes() {
-			return loader.themes();
-		},
 		resolvePath(value, cwd) {
 			return loader.resolvePath(value, cwd);
 		},

package/src/domains/resources/loader.ts

@@ -25,6 +25,8 @@ export interface ResourceList<T> {
 
 export interface ResourceLoaderOptions {
 	cwd?: string;
+	/** Slash-command names prompt templates may not claim. */
+	reservedPromptNames?: ReadonlySet<string>;
 	skills?: () => Pick<LoadSkillsInput, "trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths">;
 }
 
@@ -38,7 +40,6 @@ export interface ResourcesLoader {
 	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
 	prompts(cwd?: string): ResourceList<PromptTemplate>;
 	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
-	themes(): ResourceList<never>;
 	resolvePath(value: string, cwd?: string): string;
 	reload(): Promise<void>;
 }
@@ -53,6 +54,7 @@ export function createResourcesLoader(options: ResourceLoaderOptions = {}): Reso
 	// trust decision whichever kind is read out of it.
 	const promptOptions = (cwd: string): LoadPromptTemplatesInput => ({
 		cwd,
+		...(options.reservedPromptNames !== undefined ? { reservedNames: options.reservedPromptNames } : {}),
 		...(skillOptions().trustProjectCompatRoots !== undefined
 			? { trustProjectCompatRoots: skillOptions().trustProjectCompatRoots === true }
 			: {}),
@@ -73,9 +75,6 @@ export function createResourcesLoader(options: ResourceLoaderOptions = {}): Reso
 		expandPromptTemplate(text, cwd = defaultCwd) {
 			return expandPromptTemplateInput(text, loadPromptTemplates(promptOptions(cwd)));
 		},
-		themes() {
-			return { items: [], diagnostics: [] };
-		},
 		resolvePath(value, cwd = defaultCwd) {
 			return expandConfigPath(value, { cwd });
 		},

package/src/domains/resources/prompts/loader.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { parseCommandArgs, substituteArgs } from "../../../engine/prompt-templates.js";
 import { INTEROP_AGENT_KINDS } from "../../interop/registry.js";
 import {
 	type ResourceCandidate,
@@ -18,7 +19,6 @@ import {
 	stringField,
 } from "../common-loader.js";
 import { projectCompatTrusted } from "../skills/loader.js";
-import { parseCommandArgs, substituteArgs } from "./substitute.js";
 
 export interface PromptTemplate {
 	name: string;
@@ -51,6 +51,8 @@ export interface LoadPromptTemplatesInput {
 	home?: string;
 	/** Opt in to model-visible project compatibility roots (.claude/commands, .codex/prompts). */
 	trustProjectCompatRoots?: boolean;
+	/** Names owned by another command registry and unavailable to templates. */
+	reservedNames?: ReadonlySet<string>;
 }
 
 export type PromptTemplateExpansion =
@@ -189,8 +191,20 @@ export function loadPromptTemplates(input: LoadPromptTemplatesInput = {}): Promp
 	const diagnostics: ResourceDiagnostic[] = [];
 	const candidates = roots.flatMap((root) => loadPromptRoot(root, diagnostics));
 	const resolved = resolveResourceCollisions(candidates);
+	const items: PromptTemplate[] = [];
+	for (const template of resolved.winners) {
+		if (input.reservedNames?.has(template.name) === true) {
+			diagnostics.push({
+				type: "collision",
+				message: `prompt template /${template.name} conflicts with the built-in slash command /${template.name} and was ignored`,
+				path: template.filePath,
+			});
+			continue;
+		}
+		items.push(template);
+	}
 	return {
-		items: [...resolved.winners].sort((a, b) => a.name.localeCompare(b.name)),
+		items: items.sort((a, b) => a.name.localeCompare(b.name)),
 		diagnostics: [...diagnostics, ...resolved.diagnostics],
 	};
 }

package/src/domains/resources/prompts/substitute.ts

@@ -1,65 +1 @@
-export function parseCommandArgs(input: string): string[] {
-	const args: string[] = [];
-	let current = "";
-	let hasToken = false;
-	let quote: "'" | '"' | null = null;
-
-	const push = (): void => {
-		if (!hasToken) return;
-		args.push(current);
-		current = "";
-		hasToken = false;
-	};
-
-	for (let i = 0; i < input.length; i += 1) {
-		const ch = input[i];
-		if (!ch) continue;
-		if (quote) {
-			if (ch === quote) {
-				quote = null;
-			} else {
-				current += ch;
-			}
-			continue;
-		}
-		if (ch === "'" || ch === `"`) {
-			quote = ch;
-			hasToken = true;
-			continue;
-		}
-		if (/\s/.test(ch)) {
-			push();
-			continue;
-		}
-		current += ch;
-		hasToken = true;
-	}
-	push();
-
-	return args;
-}
-
-function sliceArgs(args: ReadonlyArray<string>, startText: string, lengthText: string | undefined): string {
-	const start = Number.parseInt(startText, 10);
-	if (!Number.isFinite(start) || start <= 0) return "";
-	const zeroBased = start - 1;
-	if (lengthText === undefined) return args.slice(zeroBased).join(" ");
-	const length = Number.parseInt(lengthText, 10);
-	if (!Number.isFinite(length) || length <= 0) return "";
-	return args.slice(zeroBased, zeroBased + length).join(" ");
-}
-
-export function substituteArgs(content: string, args: ReadonlyArray<string>): string {
-	const allArgs = args.join(" ");
-	return content
-		.replace(/\$\{@:(\d+)(?::(\d+))?\}/g, (_match, start: string, length: string | undefined) =>
-			sliceArgs(args, start, length),
-		)
-		.replace(/\$ARGUMENTS/g, allArgs)
-		.replace(/\$@/g, allArgs)
-		.replace(/\$(\d+)/g, (_match, indexText: string) => {
-			const index = Number.parseInt(indexText, 10);
-			if (!Number.isFinite(index) || index <= 0) return "";
-			return args[index - 1] ?? "";
-		});
-}
+export { parseCommandArgs, substituteArgs } from "../../../engine/prompt-templates.js";

package/src/domains/resources/skills/content-hash.ts

@@ -20,6 +20,8 @@ export const PROVENANCE_KEYS = new Set([
 	"installed-hash",
 	"installedHash",
 	"audit",
+	"installed-by",
+	"installedBy",
 ]);
 
 export interface FrontmatterRegion {

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

@@ -117,6 +117,16 @@ export function parseSkillSourceSpec(source: string): SkillSourceSpec | null {
 	return { kind: "local", path: path.resolve(expanded), original: trimmed };
 }
 
+/**
+ * Whether this process is running inside a dispatched worker rather than the
+ * operator's own interactive session. `worker/entry.ts` sets this on itself at
+ * launch, so it rides the environment into every bash-tool child a worker
+ * spawns, including a `clio-coder skills install` a worker runs directly.
+ */
+function installingAsWorker(): boolean {
+	return process.env.CLIO_CODER_WORKER_RUN === "1";
+}
+
 function yamlQuote(value: string): string {
 	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
@@ -126,6 +136,8 @@ interface ProvenanceFields {
 	installedAt: string;
 	updatedAt?: string;
 	installedHash: string;
+	/** Who ran the install: a dispatched worker, or (unmarked) the operator. */
+	installedBy?: "worker";
 }
 
 /**
@@ -152,6 +164,7 @@ function injectProvenanceFrontmatter(rawText: string, fields: ProvenanceFields):
 		`installed-hash: ${yamlQuote(fields.installedHash)}`,
 		// Audit is a human decision; installs always land unreviewed.
 		"audit: unknown",
+		...(fields.installedBy ? [`installed-by: ${yamlQuote(fields.installedBy)}`] : []),
 	];
 	const clioIndex = kept.findIndex((line) => /^clio:/.test(line));
 	if (clioIndex >= 0 && !/^clio:\s*$/.test(kept[clioIndex] as string)) {
@@ -317,6 +330,7 @@ export function installSkillFromSource(input: InstallSkillInput): InstallSkillRe
 					sourceUrl: spec.original,
 					installedAt: new Date().toISOString(),
 					installedHash,
+					...(installingAsWorker() ? { installedBy: "worker" as const } : {}),
 				}),
 				"utf8",
 			);
@@ -384,6 +398,9 @@ function updateOne(skill: Skill, force: boolean): SkillUpdateReport {
 					installedAt: skill.provenance?.installedAt ?? new Date().toISOString(),
 					updatedAt: new Date().toISOString(),
 					installedHash: remoteHash,
+					// Who installed a skill is set once; an update, worker- or
+					// operator-run, does not change who put it there originally.
+					...(skill.provenance?.installedBy ? { installedBy: skill.provenance.installedBy } : {}),
 				}),
 				"utf8",
 			);

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

@@ -67,6 +67,8 @@ export interface SkillProvenance {
 	/** Content hash of the upstream SKILL.md at install time, provenance-stripped. */
 	installedHash?: string;
 	audit?: "pass" | "warn" | "fail" | "unknown";
+	/** Who ran the install: a dispatched worker, or (unmarked) the operator. */
+	installedBy?: "worker";
 }
 
 export interface Skill {
@@ -479,7 +481,18 @@ function extractProvenance(frontmatter: Record<string, unknown>): SkillProvenanc
 	const auditRaw = field("audit");
 	const audit =
 		auditRaw === "pass" || auditRaw === "warn" || auditRaw === "fail" || auditRaw === "unknown" ? auditRaw : undefined;
-	if (!installUrl && !registryId && !registryUrl && !installedAt && !updatedAt && !installedHash && !audit)
+	const installedByRaw = field("installed-by", "installedBy");
+	const installedBy = installedByRaw === "worker" ? installedByRaw : undefined;
+	if (
+		!installUrl &&
+		!registryId &&
+		!registryUrl &&
+		!installedAt &&
+		!updatedAt &&
+		!installedHash &&
+		!audit &&
+		!installedBy
+	)
 		return undefined;
 	return {
 		...(installUrl ? { installUrl } : {}),
@@ -489,6 +502,7 @@ function extractProvenance(frontmatter: Record<string, unknown>): SkillProvenanc
 		...(updatedAt ? { updatedAt } : {}),
 		...(installedHash ? { installedHash } : {}),
 		...(audit ? { audit } : {}),
+		...(installedBy ? { installedBy } : {}),
 	};
 }
 
@@ -881,15 +895,8 @@ export function modelVisibleSkills(skills: ReadonlyArray<Skill>): Skill[] {
 
 export function parseSkillCommand(input: string): { name: string; args: string } | null {
 	const trimmed = input.trim();
-	const prefix = trimmed.startsWith("/skill:")
-		? "/skill:"
-		: trimmed.startsWith("/skills:")
-			? "/skills:"
-			: trimmed.startsWith("/skill ")
-				? "/skill "
-				: null;
-	if (!prefix) return null;
-	const rest = trimmed.slice(prefix.length).trim();
+	if (!trimmed.startsWith("/skill ")) return null;
+	const rest = trimmed.slice("/skill ".length).trim();
 	const separator = rest.search(/\s/);
 	const name = separator === -1 ? rest : rest.slice(0, separator);
 	if (name.length === 0) return null;