@pithos-kit/squiggle 0.5.0 → 0.6.0

package/README.md

@@ -39,33 +39,40 @@ pi -e ./pithos.squiggle
 ```yaml
 pi:
   extensions:
-    "@pithos-kit/squiggle": "npm:0.5.0"
+    "@pithos-kit/squiggle": "npm:0.6.0"
 ```
 
 ## Configuration
 
-Create `.pi/squiggle.json` in your project:
+Run `/squiggle config` to choose an exact correction model from providers with configured authentication, just like Translate's model picker. If none are available, run `/login` first. The picker opens directly and saves to `<cwd>/.pi/squiggle.json` (honors Pi's configured project directory name). There is no session or user-level model configuration.
+
+Model precedence is **`SQUIGGLE_MODEL` > project > default**. An environment override may still take precedence after saving, which the completion message shows. Cancelling the picker changes nothing. Existing file fields are preserved, and malformed files are not overwritten.
+
+You can still edit `.pi/squiggle.json` directly:
 
 ```json
 {
   "mode": "on",
   "model": "openai-codex/gpt-5.4-mini",
-  "maxInputChars": 500
+  "maxInputChars": 500,
+  "timeoutMs": 10000
 }
 ```
 
 Options:
 
 - `mode`: `"on"` or `"off"`
-- `model`: pi model spec in `provider/model` format
+- `model`: exact pi model spec in `provider/model` format (model IDs may contain additional slashes)
 - `maxInputChars`: maximum input length to send to the correction model
+- `timeoutMs`: correction deadline in milliseconds, from `1000` to `60000` (default: `10000`)
 
-Environment variables override the config file:
+Environment variables override the project config (except the session on/off toggle):
 
 ```bash
 SQUIGGLE_MODE=off pi
 SQUIGGLE_MODEL=openai-codex/gpt-5.4-mini pi
 SQUIGGLE_MAX_CHARS=1000 pi
+SQUIGGLE_TIMEOUT_MS=15000 pi
 ```
 
 ## Commands
@@ -74,7 +81,8 @@ Inside pi:
 
 ```text
 /squiggle toggle          # switch between on/off
-/squiggle --help          # show toggle usage
+/squiggle config          # choose and save the correction model
+/squiggle --help          # show toggle/config usage
 /squiggle-status          # show status
 /squiggle-status --help   # show status-command usage
 ```
@@ -83,6 +91,10 @@ Inside pi:
 
 The toggle state is saved in the current pi session and overrides `.pi/squiggle.json` and environment configuration for that session.
 
+The default correction model is `openai-codex/gpt-5.4-mini`. Squiggle uses only the exact configured model, never silently substituting the active coding model. `/squiggle-status` shows its exact ID, configuration source, and whether it is missing from the registry. Missing models or failed authentication leave the original prompt unchanged.
+
+If authentication or correction exceeds the configured deadline, Squiggle cancels the request, clears the spinner, and submits the original prompt unchanged. Session shutdown, reload, and an active Pi cancellation signal also cancel in-flight correction.
+
 ## Notes
 
 This package imports pi runtime packages as peer dependencies:

package/extensions/index.ts

@@ -1,12 +1,21 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
 import { complete, type UserMessage } from "@earendil-works/pi-ai";
+import * as piRuntime from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createPithosLogger, errorMetadata, modelMetadata, usageMetadata, type PithosLogger } from "./logging.ts";
 
+// Older supported Pi releases do not export CONFIG_DIR_NAME.
+const CONFIG_DIR_NAME = (piRuntime as { CONFIG_DIR_NAME?: string }).CONFIG_DIR_NAME ?? ".pi";
+
 const SQUIGGLE_HELP = `Usage: /squiggle toggle
+       /squiggle config
 
 Toggle Squiggle on or off for the current session.
+Configure an authenticated exact correction model for the project.
+Model precedence: SQUIGGLE_MODEL > project > default.
+Cancelling configuration makes no changes.
 
 Options:
   --help, -h  Show this help`;
@@ -18,35 +27,83 @@ Show whether Squiggle is enabled and which correction model it uses.
 Options:
   --help, -h  Show this help`;
 
+export type SquiggleConfig = {
+	mode: "on" | "off";
+	model: string;
+	modelScope?: "SQUIGGLE_MODEL" | "project" | "default";
+	maxInputChars: number;
+	timeoutMs: number;
+};
+
+export const DEFAULT_CORRECTION_TIMEOUT_MS = 10_000;
+export const MIN_CORRECTION_TIMEOUT_MS = 1_000;
+export const MAX_CORRECTION_TIMEOUT_MS = 60_000;
+
+type CorrectPrompt = (
+	input: string,
+	ctx: ExtensionContext,
+	config: SquiggleConfig,
+	log?: PithosLogger,
+	signal?: AbortSignal,
+) => Promise<string | null>;
+
 export function registerSquiggle(
 	pi: ExtensionAPI,
-	correctPrompt: (input: string, ctx: ExtensionContext, config: SquiggleConfig, log?: PithosLogger) => Promise<string | null> = correctWithModel,
+	correctPrompt: CorrectPrompt = correctWithModel,
 ) {
 	const log = createPithosLogger();
 	log.info("extension.register");
 	let runtimeMode: SquiggleConfig["mode"] | undefined;
+	let correctionScope = new AbortController();
+	const effectiveConfig = (cwd: string): SquiggleConfig => loadEffectiveConfig(cwd, runtimeMode);
 
 	pi.on("session_start", async (event, ctx) => {
+		correctionScope.abort();
+		correctionScope = new AbortController();
 		runtimeMode = restoreRuntimeMode(ctx);
 		log.info("session.start", { reason: event.reason, sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), runtimeMode });
 	});
 
+	pi.on("session_shutdown", async () => {
+		correctionScope.abort();
+	});
+
 	pi.registerCommand("squiggle", {
-		description: "Toggle squiggle on/off",
+		description: "Toggle squiggle on/off or configure its correction model",
+		getArgumentCompletions: (prefix) => ["toggle", "config", "--help"]
+			.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
 		handler: async (args, ctx) => {
 			log.info("command.squiggle", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), args: args.trim() });
 			if (isHelpRequest(args)) return emitHelp(ctx, SQUIGGLE_HELP);
 
 			const command = args.trim().toLowerCase();
+			if (command === "config") {
+				const model = await chooseModel(ctx);
+				if (!model) return;
+				try {
+					saveModel(join(ctx.cwd, CONFIG_DIR_NAME, "squiggle.json"), model);
+				} catch {
+					ctx.ui.notify("Could not save Squiggle configuration. Check the config file and its permissions.", "error");
+					return;
+				}
+				const effective = effectiveConfig(ctx.cwd);
+				ctx.ui.notify(`Saved ${model}. ${formatStatus(ctx, effective)}`,
+					effective.model === model ? "info" : "warning");
+				return;
+			}
 			if (command !== "toggle") {
-				ctx.ui.notify("Usage: /squiggle toggle", "warning");
+				ctx.ui.notify("Usage: /squiggle toggle | config", "warning");
 				return;
 			}
 
 			const config = loadEffectiveConfig(ctx.cwd, runtimeMode);
 			runtimeMode = config.mode === "on" ? "off" : "on";
+			if (runtimeMode === "off") {
+				correctionScope.abort();
+				correctionScope = new AbortController();
+			}
 			persistRuntimeMode(pi, runtimeMode);
-			ctx.ui.notify(formatStatus(ctx, loadEffectiveConfig(ctx.cwd, runtimeMode)), "info");
+			ctx.ui.notify(formatStatus(ctx, effectiveConfig(ctx.cwd)), "info");
 		},
 	});
 
@@ -55,19 +112,22 @@ export function registerSquiggle(
 		handler: async (args, ctx) => {
 			log.info("command.squiggle-status", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.() });
 			if (isHelpRequest(args)) return emitHelp(ctx, SQUIGGLE_STATUS_HELP);
-			ctx.ui.notify(formatStatus(ctx, loadEffectiveConfig(ctx.cwd, runtimeMode)), "info");
+			ctx.ui.notify(formatStatus(ctx, effectiveConfig(ctx.cwd)), "info");
 		},
 	});
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return { action: "continue" };
 
-		const config = loadEffectiveConfig(ctx.cwd, runtimeMode);
+		const config = effectiveConfig(ctx.cwd);
 		if (config.mode === "off") return { action: "continue" };
 		if (!event.text.trim()) return { action: "continue" };
 
 		const stopIndicator = startSquiggleIndicator(ctx);
-		const corrected = await correctPrompt(event.text, ctx, config, log).finally(stopIndicator);
+		const cancellationSignal = ctx.signal
+			? AbortSignal.any([ctx.signal, correctionScope.signal])
+			: correctionScope.signal;
+		const corrected = await correctPrompt(event.text, ctx, config, log, cancellationSignal).finally(stopIndicator);
 		if (!corrected || corrected === event.text) return { action: "continue" };
 
 		if (ctx.hasUI) ctx.ui.notify(formatColoredDiff(event.text, corrected), "info");
@@ -102,22 +162,67 @@ Task:
 const DEFAULT_CORRECTION_MODEL = "openai-codex/gpt-5.4-mini";
 const DEFAULT_MAX_LLM_INPUT_CHARS = 500;
 
-type SquiggleConfig = {
-	mode: "on" | "off";
-	model: string;
-	maxInputChars: number;
-};
+type CorrectionInterruption = "cancelled" | "timeout";
 
-async function correctWithModel(input: string, ctx: ExtensionContext, config: SquiggleConfig, log = createPithosLogger()): Promise<string | null> {
+class CorrectionInterruptedError extends Error {
+	readonly kind: CorrectionInterruption;
+
+	constructor(kind: CorrectionInterruption, timeoutMs?: number) {
+		super(kind === "timeout" ? `Correction timed out after ${formatDuration(timeoutMs!)}.` : "Correction cancelled.");
+		this.kind = kind;
+	}
+}
+
+export async function correctWithModel(
+	input: string,
+	ctx: ExtensionContext,
+	config: SquiggleConfig,
+	log = createPithosLogger(),
+	signal?: AbortSignal,
+	completePrompt: typeof complete = complete,
+): Promise<string | null> {
 	const model = selectCorrectionModel(ctx, config);
 	if (!model) return null;
 	if (input.length > config.maxInputChars) return null;
 
+	const started = Date.now();
+	const sessionId = (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.();
+	log.info("model.correct.start", { sessionId, inputChars: input.length, timeoutMs: config.timeoutMs, ...modelMetadata(model) });
+
+	if (signal?.aborted) {
+		log.warn("model.correct.cancelled", { sessionId, durationMs: Date.now() - started, inputChars: input.length, ...modelMetadata(model) });
+		return null;
+	}
+
+	const requestController = new AbortController();
+	let interruptionKind: CorrectionInterruption | undefined;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let removeAbort: (() => void) | undefined;
+	const interruption = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => {
+			interruptionKind = "timeout";
+			requestController.abort();
+			reject(new CorrectionInterruptedError("timeout", config.timeoutMs));
+		}, config.timeoutMs);
+		const onAbort = () => {
+			if (interruptionKind) return;
+			interruptionKind = "cancelled";
+			requestController.abort();
+			reject(new CorrectionInterruptedError("cancelled"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		removeAbort = () => signal?.removeEventListener("abort", onAbort);
+	});
+
 	try {
-		const started = Date.now();
-		log.info("model.correct.start", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), inputChars: input.length, ...modelMetadata(model) });
-		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-		if (!auth.ok || !auth.apiKey) return null;
+		const auth = await Promise.race([
+			ctx.modelRegistry.getApiKeyAndHeaders(model),
+			interruption,
+		]);
+		if (!auth.ok || !auth.apiKey) {
+			log.warn("model.correct.unavailable", { sessionId, durationMs: Date.now() - started, inputChars: input.length, ...modelMetadata(model) });
+			return null;
+		}
 
 		const userMessage: UserMessage = {
 			role: "user",
@@ -125,14 +230,24 @@ async function correctWithModel(input: string, ctx: ExtensionContext, config: Sq
 			timestamp: Date.now(),
 		};
 
-		const response = await complete(
-			model,
-			{ systemPrompt: CORRECTION_PROMPT, messages: [userMessage] },
-			{ apiKey: auth.apiKey, headers: auth.headers },
-		);
+		const response = await Promise.race([
+			completePrompt(
+				model,
+				{ systemPrompt: CORRECTION_PROMPT, messages: [userMessage] },
+				{ apiKey: auth.apiKey, headers: auth.headers, signal: requestController.signal },
+			),
+			interruption,
+		]);
 
 		if (response.stopReason === "aborted") {
-			log.warn("model.correct.aborted", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), durationMs: Date.now() - started, ...modelMetadata(model), usage: usageMetadata(response.usage) });
+			const metadata = { sessionId, durationMs: Date.now() - started, inputChars: input.length, ...modelMetadata(model), usage: usageMetadata(response.usage) };
+			if (interruptionKind === "timeout") {
+				log.warn("model.correct.timeout", { ...metadata, timeoutMs: config.timeoutMs });
+			} else if (interruptionKind === "cancelled" || signal?.aborted) {
+				log.warn("model.correct.cancelled", metadata);
+			} else {
+				log.warn("model.correct.aborted", metadata);
+			}
 			return null;
 		}
 
@@ -141,20 +256,35 @@ async function correctWithModel(input: string, ctx: ExtensionContext, config: Sq
 			.map((c) => c.text)
 			.join("\n")
 			.trim();
-		log.info("model.correct.complete", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), durationMs: Date.now() - started, inputChars: input.length, changed: corrected !== input, ...modelMetadata(model), usage: usageMetadata(response.usage) });
+		log.info("model.correct.complete", { sessionId, durationMs: Date.now() - started, inputChars: input.length, changed: corrected !== input, ...modelMetadata(model), usage: usageMetadata(response.usage) });
 		return corrected;
 	} catch (error) {
-		log.warn("model.correct.error", { sessionId: (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.(), inputChars: input.length, ...modelMetadata(model), error: errorMetadata(error) });
+		if (interruptionKind === "timeout" || (error instanceof CorrectionInterruptedError && error.kind === "timeout")) {
+			log.warn("model.correct.timeout", { sessionId, durationMs: Date.now() - started, inputChars: input.length, timeoutMs: config.timeoutMs, ...modelMetadata(model) });
+		} else if (interruptionKind === "cancelled" || signal?.aborted || error instanceof CorrectionInterruptedError || (error instanceof Error && error.name === "AbortError")) {
+			log.warn("model.correct.cancelled", { sessionId, durationMs: Date.now() - started, inputChars: input.length, ...modelMetadata(model) });
+		} else {
+			log.warn("model.correct.error", { sessionId, durationMs: Date.now() - started, inputChars: input.length, ...modelMetadata(model), error: errorMetadata(error) });
+		}
 		return null;
+	} finally {
+		if (timer) clearTimeout(timer);
+		removeAbort?.();
 	}
 }
 
+function formatDuration(timeoutMs: number): string {
+	return timeoutMs % 1_000 === 0 ? `${timeoutMs / 1_000}s` : `${timeoutMs}ms`;
+}
+
 function loadConfig(cwd: string): SquiggleConfig {
 	const fileConfig = readConfigFile(cwd);
 	return {
 		mode: normalizeMode(process.env.SQUIGGLE_MODE ?? fileConfig.mode) ?? "on",
 		model: process.env.SQUIGGLE_MODEL ?? fileConfig.model ?? DEFAULT_CORRECTION_MODEL,
+		modelScope: process.env.SQUIGGLE_MODEL !== undefined ? "SQUIGGLE_MODEL" : fileConfig.model !== undefined ? "project" : "default",
 		maxInputChars: normalizePositiveInt(process.env.SQUIGGLE_MAX_CHARS ?? fileConfig.maxInputChars) ?? DEFAULT_MAX_LLM_INPUT_CHARS,
+		timeoutMs: normalizeTimeoutMs(process.env.SQUIGGLE_TIMEOUT_MS ?? fileConfig.timeoutMs) ?? DEFAULT_CORRECTION_TIMEOUT_MS,
 	};
 }
 
@@ -172,16 +302,52 @@ function restoreRuntimeMode(ctx: ExtensionContext): SquiggleConfig["mode"] | und
 	return undefined;
 }
 
+function saveModel(path: string, model: string): void {
+	const current = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+	if (!current || typeof current !== "object" || Array.isArray(current)) throw new Error("Invalid config");
+	const temporaryPath = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(dirname(path), { recursive: true });
+	try {
+		writeFileSync(temporaryPath, `${JSON.stringify({ ...current, model }, null, 2)}\n`, { mode: 0o600 });
+		renameSync(temporaryPath, path);
+	} finally {
+		rmSync(temporaryPath, { force: true });
+	}
+}
+
+async function chooseModel(ctx: ExtensionCommandContext): Promise<string | undefined> {
+	if (!ctx.hasUI) {
+		emitHelp(ctx, "Squiggle configuration requires an interactive UI.");
+		return;
+	}
+	const models = ctx.modelRegistry.getAvailable()
+		.filter((model) => ctx.modelRegistry.hasConfiguredAuth(model))
+		.sort((a, b) => `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`));
+	if (!models.length) {
+		ctx.ui.notify("No authenticated correction models are available. Configure a provider with /login first.", "error");
+		return;
+	}
+	const choices = models.map((model) => `${model.provider}/${model.id} — ${model.name}`);
+	const selected = await ctx.ui.select("Exact correction model", choices);
+	const model = models[choices.indexOf(selected ?? "")];
+	return model ? `${model.provider}/${model.id}` : undefined;
+}
+
 function persistRuntimeMode(pi: ExtensionAPI, mode: SquiggleConfig["mode"]): void {
 	pi.appendEntry("squiggle-mode", { mode });
 }
 
 function formatStatus(ctx: ExtensionContext, config: SquiggleConfig): string {
-	return `squiggle is ${config.mode} (${formatModel(selectCorrectionModel(ctx, config))}).`;
+	const unavailable = selectCorrectionModel(ctx, config) ? "" : "; unavailable — run /squiggle config";
+	const source = config.modelScope === "SQUIGGLE_MODEL" ? "; SQUIGGLE_MODEL" : "";
+	return `squiggle is ${config.mode} (${config.model}${source}${unavailable}).`;
 }
 
 function readConfigFile(cwd: string): Partial<SquiggleConfig> {
-	const path = join(cwd, ".pi", "squiggle.json");
+	return readConfigPath(join(cwd, CONFIG_DIR_NAME, "squiggle.json"));
+}
+
+function readConfigPath(path: string): Partial<SquiggleConfig> {
 	if (!existsSync(path)) return {};
 	try {
 		const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
@@ -189,6 +355,7 @@ function readConfigFile(cwd: string): Partial<SquiggleConfig> {
 			mode: typeof parsed.mode === "string" ? normalizeMode(parsed.mode) : undefined,
 			model: typeof parsed.model === "string" ? parsed.model : undefined,
 			maxInputChars: normalizePositiveInt(parsed.maxInputChars),
+			timeoutMs: normalizeTimeoutMs(parsed.timeoutMs),
 		};
 	} catch {
 		return {};
@@ -204,13 +371,20 @@ function normalizePositiveInt(value: unknown): number | undefined {
 	return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+export function normalizeTimeoutMs(value: unknown): number | undefined {
+	const parsed = normalizePositiveInt(value);
+	return parsed !== undefined && parsed >= MIN_CORRECTION_TIMEOUT_MS && parsed <= MAX_CORRECTION_TIMEOUT_MS
+		? parsed
+		: undefined;
+}
+
 function selectCorrectionModel(ctx: ExtensionContext, config: SquiggleConfig) {
 	const configured = parseModelSpec(config.model);
 	if (configured) {
 		const model = ctx.modelRegistry.find(configured.provider, configured.model);
 		if (model) return model;
 	}
-	return ctx.model;
+	return undefined;
 }
 
 function parseModelSpec(spec: string): { provider: string; model: string } | null {
@@ -219,10 +393,6 @@ function parseModelSpec(spec: string): { provider: string; model: string } | nul
 	return { provider: spec.slice(0, slash), model: spec.slice(slash + 1) };
 }
 
-function formatModel(model: ReturnType<typeof selectCorrectionModel>): string {
-	return model ? `${model.provider}/${model.id}` : "no model";
-}
-
 function startSquiggleIndicator(ctx: ExtensionContext): () => void {
 	if (!ctx.hasUI) return () => {};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithos-kit/squiggle",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Quietly polish grammar and spelling in your Pi prompts.",
   "keywords": [
     "pi-package",
@@ -31,7 +31,7 @@
     "summary": "Quietly polish grammar and spelling in user prompts.",
     "minimumPi": ">=0.83.0",
     "commands": [
-      { "name": "squiggle", "usage": "/squiggle [toggle|--help]", "summary": "Toggle prompt correction." },
+      { "name": "squiggle", "usage": "/squiggle [toggle|config|--help]", "summary": "Toggle prompt correction or configure its model." },
       { "name": "squiggle-status", "usage": "/squiggle-status [--help]", "summary": "Show correction status and configuration." }
     ],
     "tools": [],
@@ -40,10 +40,11 @@
     "themes": [],
     "agents": [],
     "configuration": [
-      { "kind": "file", "key": ".pi/squiggle.json", "summary": "Project correction mode, model, and input limit." },
+      { "kind": "file", "key": ".pi/squiggle.json", "summary": "Project correction mode, model, input limit, and timeout." },
       { "kind": "environment", "key": "SQUIGGLE_MODE", "summary": "Override correction mode." },
       { "kind": "environment", "key": "SQUIGGLE_MODEL", "summary": "Override the correction model." },
-      { "kind": "environment", "key": "SQUIGGLE_MAX_CHARS", "summary": "Override the maximum corrected input length." }
+      { "kind": "environment", "key": "SQUIGGLE_MAX_CHARS", "summary": "Override the maximum corrected input length." },
+      { "kind": "environment", "key": "SQUIGGLE_TIMEOUT_MS", "summary": "Override the bounded correction timeout." }
     ]
   },
   "pi": {