@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/core/naming-compat.ts

@@ -5,6 +5,8 @@
  * producer.
  */
 
+import { hasDiagnosticSink, writeDiagnostic } from "./diagnostics.js";
+
 const warned = new Set<string>();
 
 export const LEGACY_NAMING_COMPATIBILITY_RETIREMENT = "v0.7.0";
@@ -14,11 +16,11 @@ export function warnLegacyNaming(legacy: string, canonical: string): void {
 	const key = `${legacy}\0${canonical}`;
 	if (warned.has(key)) return;
 	warned.add(key);
-	process.emitWarning(
+	const message =
 		`'${legacy}' is a deprecated Clio Coder identifier; use '${canonical}'. ` +
-			`Legacy naming compatibility is scheduled for removal in ${LEGACY_NAMING_COMPATIBILITY_RETIREMENT}.`,
-		{ code: "CLIO_CODER_LEGACY_NAMING", type: "DeprecationWarning" },
-	);
+		`Legacy naming compatibility is scheduled for removal in ${LEGACY_NAMING_COMPATIBILITY_RETIREMENT}.`;
+	if (hasDiagnosticSink()) writeDiagnostic(`[CLIO_CODER_LEGACY_NAMING] DeprecationWarning: ${message}`);
+	else process.emitWarning(message, { code: "CLIO_CODER_LEGACY_NAMING", type: "DeprecationWarning" });
 }
 
 /** Prefer a canonical environment variable and temporarily fall back to its released alias. */

package/src/core/package-root.ts

@@ -1,11 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PI_MONO_PACKAGES } from "../engine/pi-mono-names.js";
 
 let cached: string | null = null;
 let cachedClioVersion: string | null = null;
-let cachedPiMonoVersion: string | null = null;
 
 export function resolvePackageRoot(metaUrl = import.meta.url): string {
 	if (cached) return cached;
@@ -45,10 +43,3 @@ export function readClioVersion(): string {
 	cachedClioVersion = pkg.version ?? "0.0.0";
 	return cachedClioVersion;
 }
-
-export function readPiMonoVersion(): string {
-	if (cachedPiMonoVersion) return cachedPiMonoVersion;
-	const pkg = readPackageJson();
-	cachedPiMonoVersion = pkg.dependencies?.[PI_MONO_PACKAGES.agentCore] ?? "unknown";
-	return cachedPiMonoVersion;
-}

package/src/core/path-canonical.ts

@@ -1,37 +1,156 @@
-import { realpathSync } from "node:fs";
+import { readlinkSync, realpathSync } from "node:fs";
 import path from "node:path";
 
+/** Linux MAXSYMLINKS. The kernel refuses a lookup that follows more links. */
+const MAX_SYMLINK_HOPS = 40;
+
+/** Windows accepts either separator in a raw path; POSIX allows `\` in a name. */
+const RAW_SEPARATORS = path.sep === "\\" ? /[\\/]/u : /\//u;
+
+/**
+ * The realpath and readlink answers of one admission, so several walks that
+ * share ancestors inside it inspect each component once. Create one per call
+ * and drop it when the call is decided: an operator may replace a link between
+ * calls, and a memo that outlives the call would judge the next one against
+ * the old link.
+ */
+export interface PathWalkMemo {
+	/** Absolute path to its realpath, or null when realpath threw. */
+	readonly realpath: Map<string, string | null>;
+	/** Absolute path to its link target, or the error code readlink threw. */
+	readonly readlink: Map<string, { target: string } | { code: string | undefined }>;
+}
+
+export function createPathWalkMemo(): PathWalkMemo {
+	return { realpath: new Map(), readlink: new Map() };
+}
+
 /**
- * Resolve symlinks for an absolute path as far as the filesystem currently
- * exists. Existing targets return their real path; missing targets return the
- * real path of the deepest existing parent plus the unresolved tail.
+ * Resolve an absolute path to where a read or write through it would land.
+ * Existing targets return their real path. Otherwise the walk starts at the
+ * deepest ancestor realpath resolves and takes the rest one component at a
+ * time: a symlink at any component, dangling or not, is read and resolution
+ * continues against the link's directory, and the first missing component
+ * ends the walk with the rest appended unresolved.
+ *
+ * The input is resolved lexically first, so `link/..` collapses before the
+ * link is read. A path a tool call supplies goes through canonicalizeRawPath.
+ *
+ * Returns null when the path cannot be canonicalized: a link loop, more than
+ * MAX_SYMLINK_HOPS links, or a component that cannot be inspected. A
+ * containment check must treat null as outside every root.
  */
-export function canonicalizeExistingPath(absPath: string): string {
-	const resolved = path.resolve(absPath);
+export function canonicalizePath(absPath: string, memo?: PathWalkMemo): string | null {
+	return walkFrom(path.resolve(absPath), [], memo);
+}
+
+/**
+ * canonicalizePath for a raw path as a tool call or a shell command names it,
+ * relative to base unless absolute, resolved the way the kernel resolves it.
+ * path.resolve collapses `data/link/..` to `data` before the link is read; the
+ * kernel reads the link and steps up from its target, so a redirect to
+ * `data/link/../x` lands beside the target. Every component, `..` included,
+ * goes through the canonicalizePath walk. Same null contract.
+ */
+export function canonicalizeRawPath(rawPath: string, base: string, memo?: PathWalkMemo): string | null {
+	const absBase = path.isAbsolute(base) ? base : `${process.cwd()}${path.sep}${base}`;
+	const joined = path.isAbsolute(rawPath) ? rawPath : `${absBase}${path.sep}${rawPath}`;
+	const { root } = path.parse(joined);
+	const parts = joined
+		.slice(root.length)
+		.split(RAW_SEPARATORS)
+		.filter((part) => part !== "" && part !== ".");
+	const up = parts.indexOf("..");
+	// Up to the first `..` the lexical and the physical reading agree.
+	if (up === -1) return canonicalizePath(path.join(root, ...parts), memo);
+	return walkFrom(path.join(root, ...parts.slice(0, up)), parts.slice(up), memo);
+}
+
+function realpathOf(target: string, memo: PathWalkMemo | undefined): string | null {
+	if (memo?.realpath.has(target)) return memo.realpath.get(target) as string | null;
+	let resolved: string | null = null;
 	try {
-		return path.resolve(realpathSync(resolved));
+		resolved = path.resolve(realpathSync(target));
 	} catch {
-		// Fall through to parent-prefix canonicalization for missing targets and
-		// paths whose final component cannot be resolved.
+		// Missing, or a link that does not resolve.
+	}
+	memo?.realpath.set(target, resolved);
+	return resolved;
+}
+
+function readlinkOf(target: string, memo: PathWalkMemo | undefined): { target: string } | { code: string | undefined } {
+	const known = memo?.readlink.get(target);
+	if (known !== undefined) return known;
+	let answer: { target: string } | { code: string | undefined };
+	try {
+		answer = { target: readlinkSync(target) };
+	} catch (error) {
+		answer = { code: (error as NodeJS.ErrnoException).code };
 	}
+	memo?.readlink.set(target, answer);
+	return answer;
+}
 
-	const tail: string[] = [];
-	let cursor = resolved;
-	while (true) {
+/** Resolve prefix, which holds no `..`, then walk the rest one component at a time. */
+function walkFrom(prefix: string, rest: ReadonlyArray<string>, memo: PathWalkMemo | undefined): string | null {
+	const pending = [...rest];
+	let cursor = prefix;
+	let current = realpathOf(cursor, memo);
+	while (current === null) {
+		// Fall back toward the filesystem root for missing targets and for
+		// paths whose links do not resolve.
 		const parent = path.dirname(cursor);
-		if (parent === cursor) {
-			try {
-				return path.resolve(realpathSync(cursor), ...tail);
-			} catch {
-				return resolved;
-			}
-		}
-		tail.unshift(path.basename(cursor));
+		if (parent === cursor) return null;
+		pending.unshift(path.basename(cursor));
 		cursor = parent;
-		try {
-			return path.resolve(realpathSync(cursor), ...tail);
-		} catch {
-			// Keep walking toward the filesystem root.
+		current = realpathOf(cursor, memo);
+	}
+
+	// Only non-link components are appended, so current never holds a link
+	// and `..` steps up from the real directory the way the kernel does.
+	let hops = 0;
+	while (pending.length > 0) {
+		const part = pending.shift() as string;
+		if (part === ".") continue;
+		if (part === "..") {
+			current = path.dirname(current);
+			continue;
 		}
+		const next = path.join(current, part);
+		// One readlink answers missing, plain, and link in a single call, which
+		// keeps a plain missing path at one call more than realpath alone.
+		const link = readlinkOf(next, memo);
+		if ("code" in link) {
+			const { code } = link;
+			if (code === "EINVAL") {
+				current = next;
+				continue;
+			}
+			if (code === "ENOENT" || code === "ENOTDIR") {
+				// Nothing below a missing entry is a link, so the rest appends as
+				// is. A `..` in the rest climbs back to entries that can be links,
+				// and a command that creates the missing directory first passes
+				// through it as a plain one, so the walk goes on that way.
+				if (!pending.includes("..")) return path.resolve(next, ...pending);
+				current = next;
+				continue;
+			}
+			return null;
+		}
+		const { target } = link;
+		hops += 1;
+		if (hops > MAX_SYMLINK_HOPS) return null;
+		if (path.isAbsolute(target)) current = path.parse(target).root;
+		pending.unshift(...target.split(path.sep).filter(Boolean));
 	}
+	return current;
+}
+
+/**
+ * canonicalizePath for callers that key or display a path rather than decide
+ * containment. A path that cannot be canonicalized comes back lexically
+ * resolved, so the syscall that follows reports the loop itself.
+ */
+export function canonicalizeExistingPath(absPath: string, memo?: PathWalkMemo): string {
+	return canonicalizePath(absPath, memo) ?? path.resolve(absPath);
 }

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

@@ -1,13 +1,9 @@
 import { canonicalEndpointUrl } from "./endpoint-key.js";
 
 /** Runtime families whose model residency Clio can actively mutate. */
-export type ResidencyRuntimeId = "llamacpp" | "lmstudio" | "ollama-native";
+export type ResidencyRuntimeId = "llamacpp" | "lmstudio" | "ollama";
 
-const RESIDENCY_RUNTIME_IDS: ReadonlySet<string> = new Set<ResidencyRuntimeId>([
-	"llamacpp",
-	"lmstudio",
-	"ollama-native",
-]);
+const RESIDENCY_RUNTIME_IDS: ReadonlySet<string> = new Set<ResidencyRuntimeId>(["llamacpp", "lmstudio", "ollama"]);
 
 export function residencyTargetKey(runtimeId: ResidencyRuntimeId, baseUrl: string): string;
 export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null;

package/src/core/run-overrides.ts

@@ -16,7 +16,7 @@
 export const RUN_OVERRIDES_ENV = "CLIO_CODER_RUN_OVERRIDES";
 
 export interface RunOverrides {
-	/** One-run context-window override for supported local runtimes. */
+	/** One-run planning ceiling; cannot enlarge the server's context window. */
 	maxContextTokens?: number;
 	/**
 	 * One-run sampling parameter overrides. Kept as a loose numeric record

package/src/core/settings-awareness.ts

@@ -0,0 +1,108 @@
+import type { ClioSettings } from "./config.js";
+import { getAtPath } from "./session-routing.js";
+import { SETTING_CONTROLS } from "./settings-controls.js";
+import { resolveSettingsSection, settingsSectionForPath } from "./settings-navigation.js";
+
+export const AUTONOMY_HELP = {
+	"read-only": "Inspect the workspace and answer questions. Edits, execution, and dispatch are refused.",
+	suggest: "Inspect freely; ask before edits, execution, or dispatch. Useful when reviewing an unfamiliar project.",
+	"auto-edit":
+		"Edit the workspace, run recognized checks, and delegate routine work without repeated approval. Ask for unfamiliar commands, reads outside the workspace, declared outward actions, and larger dispatch plans. Safety rules still apply.",
+	"full-auto":
+		"Skip autonomy approvals, including unfamiliar commands and outward actions. Safety rules can still block or require approval. Choose this only for work you are prepared to let run unattended.",
+} as const;
+
+function describeSettingsPosture(settings: Readonly<ClioSettings>): string {
+	const worker =
+		settings.fleet.permissions.mode === "escalate"
+			? "Workers ask you when a call needs approval; unanswered requests follow the configured timeout and fallback."
+			: settings.fleet.permissions.mode === "fail"
+				? "Workers stop their run when a call needs approval."
+				: "Workers follow their allowed tool and safety policy; a call needing approval is denied and the worker can continue with allowed work.";
+	const budget =
+		settings.safety.limits.sessionCostUsd === 0
+			? "Tracked spending has no session ceiling."
+			: `Tracked session spending is capped at $${settings.safety.limits.sessionCostUsd}; unknown provider prices are not a guaranteed dollar limit.`;
+	return `${AUTONOMY_HELP[settings.safety.autonomy]} ${worker} ${budget}`;
+}
+
+const SAFE_STRING_VALUES = new Set([
+	"chat.target",
+	"chat.model",
+	"fleet.default.target",
+	"fleet.default.model",
+	"context.memory.target",
+	"context.memory.model",
+	"fleet.concurrency",
+]);
+
+/** An allowlisted projection: never serialize targets, auth, URLs, external-agent commands, or arbitrary JSON. */
+export function settingsAwareness(settings: Readonly<ClioSettings>, query = "", offset = 0, limit = 12) {
+	const area = resolveSettingsSection(query);
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+	const controls = SETTING_CONTROLS.map((control, index) => {
+		const text = `${control.path} ${control.label} ${control.description}`.toLowerCase();
+		const score = terms.filter((term) => text.includes(term)).length;
+		return { control, index, score };
+	})
+		.filter(({ control, score }) =>
+			area ? settingsSectionForPath(control.path) === area : terms.length === 0 || score > 0,
+		)
+		.sort((a, b) => (area ? a.index - b.index : b.score - a.score || a.index - b.index))
+		.map(({ control }) => control);
+	const route = (value: ClioSettings["fleet"]["default"]) => ({
+		target: value.target ?? null,
+		model: value.model ?? null,
+		thinkingLevel: value.thinkingLevel,
+		...(value.node ? { node: value.node } : {}),
+	});
+
+	const rows = controls.slice(offset, offset + limit).map((control) => {
+		const disclose =
+			control.kind === "number" ||
+			control.kind === "boolean" ||
+			Boolean(control.choices) ||
+			SAFE_STRING_VALUES.has(control.path);
+		return {
+			path: control.path,
+			label: control.label,
+			description: control.description,
+			...(disclose
+				? { value: getAtPath(settings, control.path) ?? null }
+				: { valueOmitted: "Free-form or structured value; inspect through the user settings UI." }),
+			...(control.choices ? { choices: control.choices } : {}),
+			tui: `/settings ${settingsSectionForPath(control.path)}`,
+			cli: `clio-coder configure --section ${settingsSectionForPath(control.path)}`,
+		};
+	});
+	return {
+		scope: "effective settings for the running session; includes its overrides",
+		routing: {
+			chat: route(settings.chat),
+			fleetDefault: route(settings.fleet.default),
+			profiles: Object.fromEntries(Object.entries(settings.fleet.profiles).map(([name, value]) => [name, route(value)])),
+			agentProfiles: { ...settings.fleet.agentProfiles },
+			targets: settings.targets.map((target) => ({
+				id: target.id,
+				runtime: target.runtime,
+				defaultModel: target.defaultModel ?? null,
+			})),
+			note:
+				"These are configured routes, not backend health or a guarantee of a particular dispatch. Shadow helpers use fleet routing; do not substitute the chat model for the fleet default. Agent/profile bindings, explicit requests, recipe requirements and admission can affect a run. Null means not explicitly configured, not inheritance from chat.",
+		},
+		posture: describeSettingsPosture(settings),
+		limits: {
+			sessionCostUsd: settings.safety.limits.sessionCostUsd,
+			chatToolCallsPerTurn: settings.safety.limits.chatToolCallsPerTurn,
+			workerToolCallsPerRun: settings.fleet.limits.toolCallsPerRun,
+			workerPermissionMode: settings.fleet.permissions.mode,
+			concurrency: settings.fleet.concurrency,
+		},
+		note:
+			"Answer current-configuration questions from this live snapshot; documentation describes behavior, not this session’s configured values. For zero search matches, retry this settings scope with a short key or no query instead of reading whole guides. These are configured ceilings, not remaining budgets. This read changes nothing. Guide the user to the listed UI controls; do not edit settings files or relax safety, trust, credentials, or spending limits to get past a denial. /settings supports session-only changes where available; configure saves global defaults.",
+		rows,
+		total: controls.length,
+		nextOffset: offset + rows.length < controls.length ? offset + rows.length : null,
+	};
+}