@wahack/pi-coding-agent 15.11.0

package/src/thinking.ts

@@ -0,0 +1,167 @@
+import { type ResolvedThinkingLevel, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { Effort, type Model, THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { clampThinkingLevelForModel, getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
+
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ */
+export interface ThinkingLevelMetadata {
+	value: ThinkingLevel;
+	label: string;
+	description: string;
+}
+
+const THINKING_LEVEL_METADATA: Record<ThinkingLevel, ThinkingLevelMetadata> = {
+	[ThinkingLevel.Inherit]: {
+		value: ThinkingLevel.Inherit,
+		label: "inherit",
+		description: "Inherit session default",
+	},
+	[ThinkingLevel.Off]: { value: ThinkingLevel.Off, label: "off", description: "No reasoning" },
+	[ThinkingLevel.Minimal]: {
+		value: ThinkingLevel.Minimal,
+		label: "min",
+		description: "Very brief reasoning (~1k tokens)",
+	},
+	[ThinkingLevel.Low]: { value: ThinkingLevel.Low, label: "low", description: "Light reasoning (~2k tokens)" },
+	[ThinkingLevel.Medium]: {
+		value: ThinkingLevel.Medium,
+		label: "medium",
+		description: "Moderate reasoning (~8k tokens)",
+	},
+	[ThinkingLevel.High]: { value: ThinkingLevel.High, label: "high", description: "Deep reasoning (~16k tokens)" },
+	[ThinkingLevel.XHigh]: {
+		value: ThinkingLevel.XHigh,
+		label: "xhigh",
+		description: "Maximum reasoning (~32k tokens)",
+	},
+};
+
+const THINKING_LEVELS = new Set<string>([ThinkingLevel.Inherit, ThinkingLevel.Off, ...THINKING_EFFORTS]);
+const EFFORT_LEVELS = new Set<string>(THINKING_EFFORTS);
+
+/**
+ * Parses a provider-facing effort value.
+ */
+export function parseEffort(value: string | null | undefined): Effort | undefined {
+	return value !== undefined && value !== null && EFFORT_LEVELS.has(value) ? (value as Effort) : undefined;
+}
+
+/**
+ * Parses an agent-local thinking selector.
+ */
+export function parseThinkingLevel(value: string | null | undefined): ThinkingLevel | undefined {
+	return value !== undefined && value !== null && THINKING_LEVELS.has(value) ? (value as ThinkingLevel) : undefined;
+}
+
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export function getThinkingLevelMetadata(level: ThinkingLevel): ThinkingLevelMetadata {
+	return THINKING_LEVEL_METADATA[level];
+}
+
+/**
+ * Converts an agent-local selector into the effort sent to providers.
+ */
+export function toReasoningEffort(level: ThinkingLevel | undefined): Effort | undefined {
+	if (level === undefined || level === ThinkingLevel.Off || level === ThinkingLevel.Inherit) {
+		return undefined;
+	}
+	return level;
+}
+
+/**
+ * True when a selector explicitly requests provider-side reasoning disablement.
+ */
+export function shouldDisableReasoning(level: ThinkingLevel | undefined): boolean {
+	return level === ThinkingLevel.Off;
+}
+
+/**
+ * Resolves a selector against the current model while preserving explicit "off".
+ */
+export function resolveThinkingLevelForModel(
+	model: Model | undefined,
+	level: ThinkingLevel | undefined,
+): ResolvedThinkingLevel | undefined {
+	if (level === undefined || level === ThinkingLevel.Inherit) {
+		return undefined;
+	}
+	if (level === ThinkingLevel.Off) {
+		return ThinkingLevel.Off;
+	}
+	return clampThinkingLevelForModel(model, level);
+}
+
+/**
+ * Sentinel selector for the coding-agent "auto" thinking mode. Kept entirely
+ * inside the coding-agent layer: it is never an {@link Effort} or
+ * {@link ThinkingLevel}, so provider mapping/clamping keeps seeing concrete
+ * efforts. The session resolves `auto` to a concrete effort each turn.
+ */
+export const AUTO_THINKING = "auto" as const;
+
+/** A thinking selector as configured by the user — a concrete level or `auto`. */
+export type ConfiguredThinkingLevel = ThinkingLevel | typeof AUTO_THINKING;
+
+/** Metadata used to render the `auto` selector value alongside concrete levels. */
+export interface ConfiguredThinkingLevelMetadata {
+	value: ConfiguredThinkingLevel;
+	label: string;
+	description: string;
+}
+
+const AUTO_THINKING_METADATA: ConfiguredThinkingLevelMetadata = {
+	value: AUTO_THINKING,
+	label: "auto",
+	description: "Auto-detect per prompt (low–xhigh)",
+};
+
+/**
+ * Parses a configured thinking selector, accepting `auto` in addition to every
+ * value {@link parseThinkingLevel} accepts. {@link parseThinkingLevel} itself
+ * stays strict so model-suffix parsing (`model:high`) keeps rejecting `auto`.
+ */
+export function parseConfiguredThinkingLevel(value: string | null | undefined): ConfiguredThinkingLevel | undefined {
+	if (value === AUTO_THINKING) return AUTO_THINKING;
+	return parseThinkingLevel(value);
+}
+
+/** Returns display metadata for a configured selector, including `auto`. */
+export function getConfiguredThinkingLevelMetadata(level: ConfiguredThinkingLevel): ConfiguredThinkingLevelMetadata {
+	return level === AUTO_THINKING ? AUTO_THINKING_METADATA : getThinkingLevelMetadata(level);
+}
+
+/**
+ * Resolves an auto-classified effort against the active model's supported
+ * range. Unlike {@link clampThinkingLevelForModel}, `auto` never resolves below
+ * {@link Effort.Low}: the eligible pool is the model's supported efforts at or
+ * above Low (falling back to the full supported set only when the model maxes
+ * out below Low). Within that pool the request snaps to the highest level not
+ * exceeding it, or the pool minimum when the request is below the pool.
+ */
+export function clampAutoThinkingEffort(model: Model | undefined, effort: Effort): Effort {
+	const supported = model ? getSupportedEfforts(model) : THINKING_EFFORTS;
+	if (supported.length === 0) return effort;
+	const lowIndex = THINKING_EFFORTS.indexOf(Effort.Low);
+	const eligible = supported.filter(level => THINKING_EFFORTS.indexOf(level) >= lowIndex);
+	const pool = eligible.length > 0 ? eligible : supported;
+	const requestedIndex = THINKING_EFFORTS.indexOf(effort);
+	let chosen = pool[0];
+	for (const candidate of pool) {
+		if (THINKING_EFFORTS.indexOf(candidate) > requestedIndex) break;
+		chosen = candidate;
+	}
+	return chosen;
+}
+
+/**
+ * The provisional concrete level shown while `auto` is configured but before a
+ * turn has been classified. Prefers the model's `defaultLevel`, otherwise High,
+ * clamped into the auto range. Returns `undefined` for non-reasoning models.
+ */
+export function resolveProvisionalAutoLevel(model: Model | undefined): Effort | undefined {
+	if (!model?.reasoning) return undefined;
+	return clampAutoThinkingEffort(model, model.thinking?.defaultLevel ?? Effort.High);
+}

package/src/tiny/compiled-runtime.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs";
+import * as Module from "node:module";
+import * as path from "node:path";
+
+/**
+ * Bun's compiled-binary module resolver only finds `<pkg>/index.js` for bare
+ * specifiers loaded from the *real* filesystem — it ignores `main`/`exports`
+ * (issue #1763). The tiny-model Transformers.js runtime is `bun install`ed into
+ * a cache directory at runtime, and its graph (`@huggingface/transformers` →
+ * `onnxruntime-node` → `onnxruntime-common`, plus an eager `require("sharp")`)
+ * all point `main`/`exports` at nested files, so the stock resolver cannot load
+ * any of them. We patch `Module._resolveFilename` to resolve those bare
+ * specifiers against the cache ourselves, honoring `main`/`exports`.
+ *
+ * This module is filesystem-pure aside from {@link installRuntimeModuleResolver}
+ * mutating the `node:module` resolver, so the resolution logic is unit-testable
+ * without a compiled binary.
+ */
+
+/** Conditions honored when resolving an `exports` map for a CommonJS `require`. */
+const RUNTIME_CONDITIONS: Record<string, true> = { node: true, require: true, default: true };
+
+/** Extension probes appended to a `main`/`exports` target that lacks one. */
+const RUNTIME_EXTENSIONS: readonly string[] = [".js", ".cjs", ".mjs", ".json", ".node"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Walk a conditional `exports` target (string, array of fallbacks, or a
+ * condition object) and return the first relative path that matches a runtime
+ * condition in declaration order. Returns `null` when nothing applies (e.g.
+ * `import`-only targets).
+ */
+export function selectConditionalTarget(target: unknown): string | null {
+	if (typeof target === "string") return target;
+	if (Array.isArray(target)) {
+		for (const entry of target) {
+			const resolved = selectConditionalTarget(entry);
+			if (resolved) return resolved;
+		}
+		return null;
+	}
+	if (isRecord(target)) {
+		for (const condition in target) {
+			if (!RUNTIME_CONDITIONS[condition]) continue;
+			const resolved = selectConditionalTarget(target[condition]);
+			if (resolved) return resolved;
+		}
+	}
+	return null;
+}
+
+/** Resolve a relative target inside a package to a concrete file path, probing extensions and `index`. */
+function resolveFileTarget(pkgDir: string, relative: string): string | null {
+	const base = path.join(pkgDir, relative);
+	const candidates = [base, ...RUNTIME_EXTENSIONS.map(ext => base + ext)];
+	for (const candidate of candidates) {
+		try {
+			const stat = fs.statSync(candidate);
+			if (stat.isFile()) return candidate;
+			if (stat.isDirectory()) {
+				const indexed = resolveFileTarget(candidate, "index");
+				if (indexed) return indexed;
+			}
+		} catch {
+			// missing candidate — keep probing
+		}
+	}
+	return null;
+}
+
+function resolveExportsEntry(
+	pkgDir: string,
+	exports: Record<string, unknown>,
+	subpath: string | undefined,
+): string | null {
+	let subpathMap = false;
+	for (const key in exports) {
+		subpathMap = key === "." || key.startsWith("./");
+		break;
+	}
+	if (subpathMap) {
+		const key = subpath ? `./${subpath}` : ".";
+		if (!(key in exports)) return null;
+		const target = selectConditionalTarget(exports[key]);
+		return target ? resolveFileTarget(pkgDir, target) : null;
+	}
+	// A bare condition map only describes the package root, so a subpath
+	// request falls through to plain path joining at the call site.
+	if (subpath) return null;
+	const target = selectConditionalTarget(exports);
+	return target ? resolveFileTarget(pkgDir, target) : null;
+}
+
+/**
+ * Split a bare specifier into its package name and optional subpath, handling
+ * scoped packages (`@scope/name/sub` → `@scope/name` + `sub`).
+ */
+export function splitBareSpecifier(specifier: string): { packageName: string; subpath: string | undefined } {
+	const segments = specifier.split("/");
+	const take = specifier.startsWith("@") ? 2 : 1;
+	const packageName = segments.slice(0, take).join("/");
+	const subpath = segments.length > take ? segments.slice(take).join("/") : undefined;
+	return { packageName, subpath };
+}
+
+/**
+ * Resolve a bare specifier against an installed `node_modules` directory,
+ * honoring `exports` (CommonJS conditions), then `main`, then `index.js`.
+ * Returns an absolute file path, or `null` when the package/entry is absent.
+ */
+export function resolveRuntimeModule(runtimeNodeModules: string, specifier: string): string | null {
+	const { packageName, subpath } = splitBareSpecifier(specifier);
+	const pkgDir = path.join(runtimeNodeModules, ...packageName.split("/"));
+	const manifest = readManifest(pkgDir);
+	if (!manifest) return subpath ? resolveFileTarget(pkgDir, subpath) : null;
+
+	const { exports } = manifest;
+	if (typeof exports === "string" || isRecord(exports)) {
+		const map = typeof exports === "string" ? { ".": exports } : exports;
+		const resolved = resolveExportsEntry(pkgDir, map, subpath);
+		if (resolved) return resolved;
+	}
+	if (subpath) return resolveFileTarget(pkgDir, subpath);
+	if (typeof manifest.main === "string") {
+		const resolved = resolveFileTarget(pkgDir, manifest.main);
+		if (resolved) return resolved;
+	}
+	return resolveFileTarget(pkgDir, "index.js");
+}
+
+function readManifest(pkgDir: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+		return isRecord(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+interface ModuleResolver {
+	_resolveFilename(request: string, parent: unknown, isMain: boolean, options?: unknown): string;
+}
+
+const PATCHED = Symbol.for("omp.tiny.compiledRuntimeResolver");
+
+interface ResolverOptions {
+	/** Absolute path to the runtime cache's `node_modules`. */
+	runtimeNodeModules: string;
+	/** Bare specifier → absolute file path overrides (e.g. `sharp` → no-op stub). */
+	stubs?: Record<string, string>;
+}
+
+/**
+ * Patch `node:module`'s resolver (idempotently) so bare specifiers that the
+ * stock compiled-binary resolver cannot find fall back to the runtime cache.
+ * Stock resolution is tried first, so this never changes behavior for modules
+ * that already resolve (the worker's own bundled imports, node builtins).
+ */
+export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }: ResolverOptions): void {
+	const resolver = (Module as unknown as { default?: ModuleResolver } & ModuleResolver).default ?? Module;
+	const target = resolver as unknown as ModuleResolver & { [PATCHED]?: boolean };
+	if (target[PATCHED]) return;
+	const original = target._resolveFilename.bind(target);
+	target._resolveFilename = (request: string, parent: unknown, isMain: boolean, options?: unknown): string => {
+		try {
+			return original(request, parent, isMain, options);
+		} catch (error) {
+			const stub = stubs[request];
+			if (stub) return stub;
+			const resolved = resolveRuntimeModule(runtimeNodeModules, request);
+			if (resolved) return resolved;
+			throw error;
+		}
+	};
+	target[PATCHED] = true;
+}

package/src/tiny/device.ts

@@ -0,0 +1,111 @@
+import type { DeviceType } from "@huggingface/transformers";
+import { $env } from "@oh-my-pi/pi-utils";
+
+export type TinyModelDevice = DeviceType;
+
+export interface TinyModelDevicePreference {
+	device: TinyModelDevice;
+	raw: string | undefined;
+}
+
+const CPU_DEVICE: TinyModelDevice = "cpu";
+const CPU_ONLY_ORDER: readonly TinyModelDevice[] = [CPU_DEVICE];
+const DARWIN_WEBGPU_UNSAFE_ORDER: readonly TinyModelDevice[] = [CPU_DEVICE];
+
+const DEVICE_VALUES: Record<TinyModelDevice, true> = {
+	auto: true,
+	gpu: true,
+	cpu: true,
+	wasm: true,
+	webgpu: true,
+	cuda: true,
+	dml: true,
+	coreml: true,
+	webnn: true,
+	"webnn-npu": true,
+	"webnn-gpu": true,
+	"webnn-cpu": true,
+};
+
+function usesDarwinWorkerWebGpu(device: TinyModelDevice): boolean {
+	return process.platform === "darwin" && (device === "gpu" || device === "webgpu" || device === "auto");
+}
+
+export function normalizeTinyModelDevice(value: string | undefined): TinyModelDevice | undefined {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return undefined;
+	if (raw === "metal") return "webgpu";
+	if (raw in DEVICE_VALUES) return raw as TinyModelDevice;
+	throw new Error(
+		`Unsupported PI_TINY_DEVICE=${JSON.stringify(value)}. Use cpu, gpu, metal, webgpu, auto, cuda, dml, coreml, wasm, webnn, webnn-gpu, webnn-cpu, or webnn-npu.`,
+	);
+}
+
+export function resolveTinyModelDevicePreference(
+	value: string | undefined = $env.PI_TINY_DEVICE,
+): TinyModelDevicePreference {
+	return {
+		device: normalizeTinyModelDevice(value) ?? CPU_DEVICE,
+		raw: value,
+	};
+}
+
+export function tinyModelDeviceLoadOrder(preference: TinyModelDevicePreference): readonly TinyModelDevice[] {
+	if (preference.device === CPU_DEVICE) return CPU_ONLY_ORDER;
+	if (usesDarwinWorkerWebGpu(preference.device)) return DARWIN_WEBGPU_UNSAFE_ORDER;
+	return [preference.device, CPU_DEVICE];
+}
+
+/** Sentinel `providers.tinyModelDevice` value meaning "use the built-in CPU default". */
+export const TINY_MODEL_DEVICE_DEFAULT = "default";
+
+/** Accepted values for the `providers.tinyModelDevice` setting (validation + UI). */
+export const TINY_MODEL_DEVICE_SETTING_VALUES = [
+	TINY_MODEL_DEVICE_DEFAULT,
+	"gpu",
+	"cpu",
+	"metal",
+	"webgpu",
+	"cuda",
+	"dml",
+	"coreml",
+	"auto",
+	"wasm",
+	"webnn",
+	"webnn-gpu",
+	"webnn-cpu",
+	"webnn-npu",
+] as const;
+
+/** Submenu metadata for the `providers.tinyModelDevice` setting. */
+export const TINY_MODEL_DEVICE_SETTING_OPTIONS = [
+	{ value: "default", label: "Default", description: "CPU-only inference" },
+	{ value: "gpu", label: "GPU", description: "Accelerated provider (WebGPU/Metal, CUDA, or DirectML)" },
+	{ value: "cpu", label: "CPU", description: "CPU-only inference" },
+	{ value: "metal", label: "Metal", description: "WebGPU alias for Apple GPUs" },
+	{ value: "webgpu", label: "WebGPU", description: "WebGPU/Metal backend" },
+	{ value: "cuda", label: "CUDA", description: "NVIDIA CUDA (Linux x64)" },
+	{ value: "dml", label: "DirectML", description: "DirectML backend (Windows)" },
+	{ value: "coreml", label: "CoreML", description: "Apple CoreML (opt-in; can fail to load)" },
+	{ value: "auto", label: "Auto", description: "Let ONNX Runtime choose a provider" },
+	{ value: "wasm", label: "WASM", description: "WebAssembly backend" },
+	{ value: "webnn", label: "WebNN", description: "WebNN backend" },
+	{ value: "webnn-gpu", label: "WebNN GPU", description: "WebNN GPU device" },
+	{ value: "webnn-cpu", label: "WebNN CPU", description: "WebNN CPU device" },
+	{ value: "webnn-npu", label: "WebNN NPU", description: "WebNN NPU device" },
+] as const satisfies ReadonlyArray<{
+	value: (typeof TINY_MODEL_DEVICE_SETTING_VALUES)[number];
+	label: string;
+	description: string;
+}>;
+
+/**
+ * Map a `providers.tinyModelDevice` setting value onto a `PI_TINY_DEVICE` env
+ * value for the worker. Returns `undefined` for the default sentinel so the
+ * worker keeps its built-in CPU default; the worker still validates the
+ * forwarded value via {@link normalizeTinyModelDevice}.
+ */
+export function tinyModelDeviceSettingToEnv(value: string | undefined): string | undefined {
+	if (!value || value === TINY_MODEL_DEVICE_DEFAULT) return undefined;
+	return value;
+}

package/src/tiny/dtype.ts

@@ -0,0 +1,101 @@
+import type { DataType } from "@huggingface/transformers";
+import { $env } from "@oh-my-pi/pi-utils";
+
+/** ONNX quantization / precision for local tiny models (transformers.js `dtype`). */
+export type TinyModelDtype = DataType;
+
+const DTYPE_VALUES: Record<TinyModelDtype, true> = {
+	auto: true,
+	fp32: true,
+	fp16: true,
+	q8: true,
+	int8: true,
+	uint8: true,
+	q4: true,
+	bnb4: true,
+	q4f16: true,
+	q2: true,
+	q2f16: true,
+	q1: true,
+	q1f16: true,
+};
+
+/**
+ * Validate and canonicalize a `PI_TINY_DTYPE` value. Returns `undefined` when
+ * unset/blank so callers fall back to the per-model spec dtype, and throws on an
+ * unrecognized value so a misconfiguration fails loudly instead of silently
+ * loading a different precision than requested.
+ */
+export function normalizeTinyModelDtype(value: string | undefined): TinyModelDtype | undefined {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return undefined;
+	if (raw in DTYPE_VALUES) return raw as TinyModelDtype;
+	throw new Error(
+		`Unsupported PI_TINY_DTYPE=${JSON.stringify(value)}. Use auto, fp32, fp16, q8, int8, uint8, q4, bnb4, q4f16, q2, q2f16, q1, or q1f16.`,
+	);
+}
+
+/**
+ * Resolve the `PI_TINY_DTYPE` override. `undefined` means "use the per-model spec
+ * dtype" (currently `q4` for every shipped model); a concrete value overrides the
+ * precision for whichever local tiny model loads.
+ */
+export function resolveTinyModelDtypeOverride(
+	value: string | undefined = $env.PI_TINY_DTYPE,
+): TinyModelDtype | undefined {
+	return normalizeTinyModelDtype(value);
+}
+
+/** Sentinel `providers.tinyModelDtype` value meaning "use each model's shipped dtype". */
+export const TINY_MODEL_DTYPE_DEFAULT = "default";
+
+/** Accepted values for the `providers.tinyModelDtype` setting (validation + UI). */
+export const TINY_MODEL_DTYPE_SETTING_VALUES = [
+	TINY_MODEL_DTYPE_DEFAULT,
+	"q4",
+	"q4f16",
+	"q8",
+	"fp16",
+	"fp32",
+	"int8",
+	"uint8",
+	"bnb4",
+	"q2",
+	"q2f16",
+	"q1",
+	"q1f16",
+	"auto",
+] as const;
+
+/** Submenu metadata for the `providers.tinyModelDtype` setting. */
+export const TINY_MODEL_DTYPE_SETTING_OPTIONS = [
+	{ value: "default", label: "Default", description: "Each model's shipped dtype (currently q4)" },
+	{ value: "q4", label: "q4", description: "4-bit weights; smallest and fastest" },
+	{ value: "q4f16", label: "q4f16", description: "4-bit weights with fp16 activations" },
+	{ value: "q8", label: "q8", description: "8-bit quantization" },
+	{ value: "fp16", label: "fp16", description: "16-bit float; higher fidelity, larger" },
+	{ value: "fp32", label: "fp32", description: "Full precision; largest and slowest" },
+	{ value: "int8", label: "int8", description: "Signed 8-bit integer" },
+	{ value: "uint8", label: "uint8", description: "Unsigned 8-bit integer" },
+	{ value: "bnb4", label: "bnb4", description: "bitsandbytes 4-bit" },
+	{ value: "q2", label: "q2", description: "2-bit weights" },
+	{ value: "q2f16", label: "q2f16", description: "2-bit weights with fp16 activations" },
+	{ value: "q1", label: "q1", description: "1-bit weights" },
+	{ value: "q1f16", label: "q1f16", description: "1-bit weights with fp16 activations" },
+	{ value: "auto", label: "Auto", description: "Let transformers.js choose per device" },
+] as const satisfies ReadonlyArray<{
+	value: (typeof TINY_MODEL_DTYPE_SETTING_VALUES)[number];
+	label: string;
+	description: string;
+}>;
+
+/**
+ * Map a `providers.tinyModelDtype` setting value onto a `PI_TINY_DTYPE` env value
+ * for the worker. Returns `undefined` for the default sentinel so the worker keeps
+ * each model's shipped dtype; the worker still validates the forwarded value via
+ * {@link normalizeTinyModelDtype}.
+ */
+export function tinyModelDtypeSettingToEnv(value: string | undefined): string | undefined {
+	if (!value || value === TINY_MODEL_DTYPE_DEFAULT) return undefined;
+	return value;
+}