@oh-my-pi/pi-coding-agent 14.1.2 → 14.2.0

package/src/tools/todo-write.ts

@@ -42,14 +42,13 @@ export interface TodoWriteToolDetails {
 // Schema
 // =============================================================================
 
-const StatusEnum = StringEnum(["pending", "in_progress", "completed", "abandoned"] as const, {
-	description: "Task status",
-});
-
 const InputTask = Type.Object({
 	content: Type.String({ description: "Task description" }),
-	status: Type.Optional(StatusEnum),
-	notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
+	status: Type.Optional(
+		StringEnum(["pending", "in_progress", "completed", "abandoned"] as const, {
+			description: "Task status",
+		}),
+	),
 	details: Type.Optional(
 		Type.String({ description: "Implementation details, file paths, and specifics (shown only when active)" }),
 	),
@@ -60,39 +59,26 @@ const InputPhase = Type.Object({
 	tasks: Type.Optional(Type.Array(InputTask)),
 });
 
+const AddNoteEntry = Type.Object({
+	id: Type.String({ description: "Task ID, e.g. task-3" }),
+	notes: Type.String({ description: "Notes to append" }),
+});
+
+const AddTaskEntry = Type.Object({
+	phase: Type.String({ description: "Phase name or ID" }),
+	content: Type.String({ description: "Task description" }),
+	details: Type.Optional(Type.String({ description: "Implementation details, file paths, and specifics" })),
+});
+
 const todoWriteSchema = Type.Object({
-	ops: Type.Array(
-		Type.Union([
-			Type.Object({
-				op: Type.Literal("replace"),
-				phases: Type.Array(InputPhase),
-			}),
-			Type.Object({
-				op: Type.Literal("add_phase"),
-				name: Type.String({ description: "Phase name" }),
-				tasks: Type.Optional(Type.Array(InputTask)),
-			}),
-			Type.Object({
-				op: Type.Literal("add_task"),
-				phase: Type.String({ description: "Phase ID, e.g. phase-1" }),
-				content: Type.String({ description: "Task description" }),
-				notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
-				details: Type.Optional(Type.String({ description: "Implementation details, file paths, and specifics" })),
-			}),
-			Type.Object({
-				op: Type.Literal("update"),
-				id: Type.String({ description: "Task ID, e.g. task-3" }),
-				status: Type.Optional(StatusEnum),
-				content: Type.Optional(Type.String({ description: "Updated task description" })),
-				notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
-				details: Type.Optional(Type.String({ description: "Updated details" })),
-			}),
-			Type.Object({
-				op: Type.Literal("remove_task"),
-				id: Type.String({ description: "Task ID, e.g. task-3" }),
-			}),
-		]),
-	),
+	phases: Type.Optional(Type.Array(InputPhase, { description: "Replace entire todo list with these phases" })),
+	start: Type.Optional(Type.String({ description: "Task ID to start, e.g. task-3" })),
+	complete: Type.Optional(Type.Array(Type.String(), { description: "Task IDs to mark completed" })),
+	abandon: Type.Optional(Type.Array(Type.String(), { description: "Task IDs to mark abandoned" })),
+	remove: Type.Optional(Type.Array(Type.String(), { description: "Task IDs to remove" })),
+	add_notes: Type.Optional(Type.Array(AddNoteEntry, { description: "Notes to append to tasks" })),
+	add_tasks: Type.Optional(Type.Array(AddTaskEntry, { description: "Tasks to add" })),
+	add_phase: Type.Optional(InputPhase),
 });
 
 type TodoWriteParams = Static<typeof todoWriteSchema>;
@@ -124,7 +110,7 @@ function findTask(phases: TodoPhase[], id: string): TodoItem | undefined {
 }
 
 function buildPhaseFromInput(
-	input: { name: string; tasks?: Array<{ content: string; status?: TodoStatus; notes?: string; details?: string }> },
+	input: { name: string; tasks?: Array<{ content: string; status?: TodoStatus; details?: string }> },
 	phaseId: string,
 	nextTaskId: number,
 ): { phase: TodoPhase; nextTaskId: number } {
@@ -135,7 +121,6 @@ function buildPhaseFromInput(
 			id: `task-${tid++}`,
 			content: t.content,
 			status: t.status ?? "pending",
-			notes: t.notes,
 			details: t.details,
 		});
 	}
@@ -207,79 +192,108 @@ export function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPha
 	return [];
 }
 
-function applyOps(file: TodoFile, ops: TodoWriteParams["ops"]): { file: TodoFile; errors: string[] } {
+function resolveTaskOrError(phases: TodoPhase[], id: string, errors: string[]): TodoItem | undefined {
+	const task = findTask(phases, id);
+	if (!task) {
+		const totalTasks = phases.reduce((sum, p) => sum + p.tasks.length, 0);
+		const hint = totalTasks === 0 ? " (todo list is empty — was it replaced or not yet created?)" : "";
+		errors.push(`Task "${id}" not found${hint}`);
+	}
+	return task;
+}
+
+function applyParams(file: TodoFile, params: TodoWriteParams): { file: TodoFile; errors: string[] } {
 	const errors: string[] = [];
 
-	for (const op of ops) {
-		switch (op.op) {
-			case "replace": {
-				const next = makeEmptyFile();
-				for (const inputPhase of op.phases) {
-					const phaseId = `phase-${next.nextPhaseId++}`;
-					const { phase, nextTaskId } = buildPhaseFromInput(inputPhase, phaseId, next.nextTaskId);
-					next.phases.push(phase);
-					next.nextTaskId = nextTaskId;
-				}
-				file = next;
-				break;
-			}
+	// Replace (must be first — replaces entire state)
+	if (params.phases) {
+		const next = makeEmptyFile();
+		for (const inputPhase of params.phases) {
+			const phaseId = `phase-${next.nextPhaseId++}`;
+			const { phase, nextTaskId } = buildPhaseFromInput(inputPhase, phaseId, next.nextTaskId);
+			next.phases.push(phase);
+			next.nextTaskId = nextTaskId;
+		}
+		file = next;
+	}
+
+	if (params.add_phase) {
+		const phaseId = `phase-${file.nextPhaseId++}`;
+		const { phase, nextTaskId } = buildPhaseFromInput(params.add_phase, phaseId, file.nextTaskId);
+		file.phases.push(phase);
+		file.nextTaskId = nextTaskId;
+	}
 
-			case "add_phase": {
-				const phaseId = `phase-${file.nextPhaseId++}`;
-				const { phase, nextTaskId } = buildPhaseFromInput(op, phaseId, file.nextTaskId);
-				file.phases.push(phase);
-				file.nextTaskId = nextTaskId;
-				break;
+	if (params.add_tasks) {
+		for (const entry of params.add_tasks) {
+			const target = file.phases.find(p => p.id === entry.phase || p.name === entry.phase);
+			if (!target) {
+				errors.push(`Phase "${entry.phase}" not found`);
+				continue;
 			}
+			target.tasks.push({
+				id: `task-${file.nextTaskId++}`,
+				content: entry.content,
+				status: "pending",
+				details: entry.details,
+			});
+		}
+	}
+
+	if (params.complete) {
+		for (const id of params.complete) {
+			const task = resolveTaskOrError(file.phases, id, errors);
+			if (task) task.status = "completed";
+		}
+	}
 
-			case "add_task": {
-				const target = file.phases.find(p => p.id === op.phase);
-				if (!target) {
-					errors.push(`Phase "${op.phase}" not found`);
+	if (params.abandon) {
+		for (const id of params.abandon) {
+			const task = resolveTaskOrError(file.phases, id, errors);
+			if (task) task.status = "abandoned";
+		}
+	}
+
+	if (params.remove) {
+		for (const id of params.remove) {
+			let removed = false;
+			for (const phase of file.phases) {
+				const idx = phase.tasks.findIndex(t => t.id === id);
+				if (idx !== -1) {
+					phase.tasks.splice(idx, 1);
+					removed = true;
 					break;
 				}
-				target.tasks.push({
-					id: `task-${file.nextTaskId++}`,
-					content: op.content,
-					status: "pending",
-					notes: op.notes,
-					details: op.details,
-				});
-				break;
 			}
+			if (!removed) {
+				const totalTasks = file.phases.reduce((sum, p) => sum + p.tasks.length, 0);
+				const hint = totalTasks === 0 ? " (todo list is empty)" : "";
+				errors.push(`Task "${id}" not found${hint}`);
+			}
+		}
+	}
 
-			case "update": {
-				const task = findTask(file.phases, op.id);
-				if (!task) {
-					const totalTasks = file.phases.reduce((sum, p) => sum + p.tasks.length, 0);
-					const hint = totalTasks === 0 ? " (todo list is empty — was it replaced or not yet created?)" : "";
-					errors.push(`Task "${op.id}" not found${hint}`);
-					break;
-				}
-				if (op.status !== undefined) task.status = op.status;
-				if (op.content !== undefined) task.content = op.content;
-				if (op.notes !== undefined) task.notes = op.notes;
-				if (op.details !== undefined) task.details = op.details;
-				break;
+	if (params.add_notes) {
+		for (const entry of params.add_notes) {
+			const task = resolveTaskOrError(file.phases, entry.id, errors);
+			if (task) {
+				task.notes = task.notes ? `${task.notes}\n${entry.notes}` : entry.notes;
 			}
+		}
+	}
 
-			case "remove_task": {
-				let removed = false;
-				for (const phase of file.phases) {
-					const idx = phase.tasks.findIndex(t => t.id === op.id);
-					if (idx !== -1) {
-						phase.tasks.splice(idx, 1);
-						removed = true;
-						break;
+	if (params.start) {
+		const task = resolveTaskOrError(file.phases, params.start, errors);
+		if (task) {
+			// Demote any currently in_progress tasks before promoting the target
+			for (const phase of file.phases) {
+				for (const t of phase.tasks) {
+					if (t.status === "in_progress" && t.id !== task.id) {
+						t.status = "pending";
 					}
 				}
-				if (!removed) {
-					const totalTasks = file.phases.reduce((sum, p) => sum + p.tasks.length, 0);
-					const hint = totalTasks === 0 ? " (todo list is empty)" : "";
-					errors.push(`Task "${op.id}" not found${hint}`);
-				}
-				break;
 			}
+			task.status = "in_progress";
 		}
 	}
 
@@ -318,6 +332,11 @@ function formatSummary(phases: TodoPhase[], errors: string[]): string {
 					lines.push(`      ${line}`);
 				}
 			}
+			if (task.notes) {
+				for (const line of task.notes.split("\n")) {
+					lines.push(`      Note: ${line}`);
+				}
+			}
 		}
 	}
 	lines.push(
@@ -365,7 +384,7 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 	): Promise<AgentToolResult<TodoWriteToolDetails>> {
 		const previousPhases = this.session.getTodoPhases?.() ?? [];
 		const current = fileFromPhases(previousPhases);
-		const { file: updated, errors } = applyOps(current, params.ops);
+		const { file: updated, errors } = applyParams(current, params);
 		this.session.setTodoPhases?.(updated.phases);
 		const storage = this.session.getSessionFile() ? "session" : "memory";
 
@@ -381,7 +400,14 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 // =============================================================================
 
 interface TodoWriteRenderArgs {
-	ops?: Array<{ op: string }>;
+	phases?: unknown;
+	start?: string;
+	complete?: string[];
+	abandon?: string[];
+	remove?: string[];
+	add_notes?: unknown[];
+	add_tasks?: unknown[];
+	add_phase?: unknown;
 }
 
 function formatTodoLine(item: TodoItem, uiTheme: Theme, prefix: string): string {
@@ -404,8 +430,16 @@ function formatTodoLine(item: TodoItem, uiTheme: Theme, prefix: string): string
 
 export const todoWriteToolRenderer = {
 	renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
-		const count = args.ops?.length ?? 0;
-		const label = count === 1 ? (args.ops?.[0]?.op ?? "update") : `${count} ops`;
+		const ops: string[] = [];
+		if (args.phases) ops.push("replace");
+		if (args.complete?.length) ops.push(`complete ${args.complete.length}`);
+		if (args.start) ops.push("start");
+		if (args.abandon?.length) ops.push("abandon");
+		if (args.remove?.length) ops.push("remove");
+		if (args.add_notes?.length) ops.push("add_notes");
+		if (args.add_tasks?.length) ops.push("add_tasks");
+		if (args.add_phase) ops.push("add_phase");
+		const label = ops.length > 0 ? ops.join(", ") : "update";
 		const text = renderStatusLine({ icon: "pending", title: "Todo Write", meta: [label] }, uiTheme);
 		return new Text(text, 0, 0);
 	},

package/src/tools/write.ts

@@ -1,13 +1,7 @@
 import { Database } from "bun:sqlite";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type {
-	AgentTool,
-	AgentToolContext,
-	AgentToolResult,
-	AgentToolUpdateCallback,
-	ToolCallContext,
-} from "@oh-my-pi/pi-agent-core";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, isRecord, prompt, untilAborted } from "@oh-my-pi/pi-utils";
@@ -32,6 +26,7 @@ import {
 	formatMoreItems,
 	formatStatusIcon,
 	formatTitle,
+	getLspBatchRequest,
 	replaceTabs,
 	shortenPath,
 } from "./render-utils";
@@ -61,22 +56,6 @@ export interface WriteToolDetails {
 	meta?: OutputMeta;
 }
 
-const LSP_BATCH_TOOLS = new Set(["edit", "write"]);
-
-function getLspBatchRequest(toolCall: ToolCallContext | undefined): { id: string; flush: boolean } | undefined {
-	if (!toolCall) {
-		return undefined;
-	}
-	const hasOtherWrites = toolCall.toolCalls.some(
-		(call, index) => index !== toolCall.index && LSP_BATCH_TOOLS.has(call.name),
-	);
-	if (!hasOtherWrites) {
-		return undefined;
-	}
-	const hasLaterWrites = toolCall.toolCalls.slice(toolCall.index + 1).some(call => LSP_BATCH_TOOLS.has(call.name));
-	return { id: toolCall.batchId, flush: !hasLaterWrites };
-}
-
 /**
  * Strip hashline display prefixes from write content.
  *

package/src/tui/code-cell.ts

@@ -18,7 +18,7 @@ export interface CodeCellOptions {
 	index?: number;
 	total?: number;
 	title?: string;
-	status?: "pending" | "running" | "complete" | "error";
+	status?: "pending" | "running" | "warning" | "complete" | "error";
 	spinnerFrame?: number;
 	duration?: number;
 	output?: string;
@@ -32,6 +32,7 @@ function getState(status?: CodeCellOptions["status"]): State | undefined {
 	if (!status) return undefined;
 	if (status === "complete") return "success";
 	if (status === "error") return "error";
+	if (status === "warning") return "warning";
 	if (status === "running") return "running";
 	return "pending";
 }
@@ -45,9 +46,11 @@ function formatHeader(options: CodeCellOptions, theme: Theme): { title: string;
 				? "success"
 				: status === "error"
 					? "error"
-					: status === "running"
-						? "running"
-						: "pending",
+					: status === "warning"
+						? "warning"
+						: status === "running"
+							? "running"
+							: "pending",
 			theme,
 			spinnerFrame,
 		);
@@ -78,10 +81,12 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 	const { title, meta } = formatHeader(options, theme);
 	const state = getState(options.status);
 
-	const rawCodeLines = highlightCode(replaceTabs(code ?? ""), language);
+	const normalizedCode = replaceTabs(code ?? "");
+	const rawCodeLines = normalizedCode.split("\n");
 	const maxCodeLines = expanded ? rawCodeLines.length : Math.min(rawCodeLines.length, codeMaxLines);
-	const codeLines = rawCodeLines.slice(0, maxCodeLines);
-	const hiddenCodeLines = rawCodeLines.length - codeLines.length;
+	const visibleCode = rawCodeLines.slice(0, maxCodeLines).join("\n");
+	const codeLines = highlightCode(visibleCode, language);
+	const hiddenCodeLines = rawCodeLines.length - maxCodeLines;
 	if (hiddenCodeLines > 0) {
 		const hint = formatExpandHint(theme, expanded, hiddenCodeLines > 0);
 		const moreLine = `${formatMoreItems(hiddenCodeLines, "line")}${hint ? ` ${hint}` : ""}`;

package/src/utils/edit-mode.ts

@@ -1,10 +1,11 @@
 import { $env, $flag } from "@oh-my-pi/pi-utils";
 
-export type EditMode = "replace" | "patch" | "hashline" | "chunk" | "vim";
+export type EditMode = "replace" | "patch" | "hashline" | "chunk" | "vim" | "apply_patch";
 
 export const DEFAULT_EDIT_MODE: EditMode = "hashline";
 
 const EDIT_MODE_IDS = {
+	apply_patch: "apply_patch",
 	chunk: "chunk",
 	hashline: "hashline",
 	patch: "patch",
@@ -38,7 +39,7 @@ export function resolveEditMode(session: EditModeSessionLike): EditMode {
 	if (envMode) return envMode;
 
 	if (!$flag("PI_STRICT_EDIT_MODE")) {
-		if (activeModel?.includes("spark")) return "replace";
+		if (activeModel?.includes("spark")) return "apply_patch";
 		if (activeModel?.includes("nano")) return "replace";
 		if (activeModel?.includes("mini")) return "replace";
 		if (activeModel?.includes("haiku")) return "replace";

package/src/utils/git.ts

@@ -190,7 +190,7 @@ async function runCommand(
 	const commandArgs = withShortLivedGitConfig(options.readOnly ? withNoOptionalLocks(args) : [...args]);
 	const child = Bun.spawn(["git", ...commandArgs], {
 		cwd,
-		env: options.env ? { ...process.env, ...options.env } : undefined,
+		env: options.env ? { ...process.env, GIT_OPTIONAL_LOCKS: "0", ...options.env } : undefined,
 		signal: options.signal,
 		stdin: normalizeStdin(options.stdin),
 		stdout: "pipe",

package/src/vim/engine.ts

@@ -294,6 +294,23 @@ function findParagraphEnd(lines: string[], line: number): number {
 	return index;
 }
 
+function cloneUndoStack(stack: VimUndoEntry[]): VimUndoEntry[] {
+	return stack.map(entry => ({
+		before: {
+			...entry.before,
+			lines: [...entry.before.lines],
+			cursor: clonePosition(entry.before.cursor),
+			baseFingerprint: entry.before.baseFingerprint ? { ...entry.before.baseFingerprint } : null,
+		},
+		after: {
+			...entry.after,
+			lines: [...entry.after.lines],
+			cursor: clonePosition(entry.after.cursor),
+			baseFingerprint: entry.after.baseFingerprint ? { ...entry.after.baseFingerprint } : null,
+		},
+	}));
+}
+
 export class VimEngine {
 	buffer: VimBuffer;
 	inputMode: VimInputMode = "normal";
@@ -361,34 +378,8 @@ export class VimEngine {
 					inserted: this.#pendingChange.inserted,
 				}
 			: null;
-		next.#undoStack = this.#undoStack.map(entry => ({
-			before: {
-				...entry.before,
-				lines: [...entry.before.lines],
-				cursor: clonePosition(entry.before.cursor),
-				baseFingerprint: entry.before.baseFingerprint ? { ...entry.before.baseFingerprint } : null,
-			},
-			after: {
-				...entry.after,
-				lines: [...entry.after.lines],
-				cursor: clonePosition(entry.after.cursor),
-				baseFingerprint: entry.after.baseFingerprint ? { ...entry.after.baseFingerprint } : null,
-			},
-		}));
-		next.#redoStack = this.#redoStack.map(entry => ({
-			before: {
-				...entry.before,
-				lines: [...entry.before.lines],
-				cursor: clonePosition(entry.before.cursor),
-				baseFingerprint: entry.before.baseFingerprint ? { ...entry.before.baseFingerprint } : null,
-			},
-			after: {
-				...entry.after,
-				lines: [...entry.after.lines],
-				cursor: clonePosition(entry.after.cursor),
-				baseFingerprint: entry.after.baseFingerprint ? { ...entry.after.baseFingerprint } : null,
-			},
-		}));
+		next.#undoStack = cloneUndoStack(this.#undoStack);
+		next.#redoStack = cloneUndoStack(this.#redoStack);
 		return next;
 	}
 
@@ -913,22 +904,14 @@ export class VimEngine {
 			}
 			case "d": {
 				await this.#applyAtomicChange(tokens, () => {
-					this.register = {
-						kind: visual.linewise ? "line" : "char",
-						text: this.buffer.getText().slice(visual.start, visual.end),
-					};
-					this.buffer.deleteOffsets(visual.start, visual.end);
+					this.#yankAndDeleteRange(visual);
 				});
 				this.#clearSelection();
 				return;
 			}
 			case "c": {
 				await this.#startInsertChange(tokens, () => {
-					this.register = {
-						kind: visual.linewise ? "line" : "char",
-						text: this.buffer.getText().slice(visual.start, visual.end),
-					};
-					this.buffer.deleteOffsets(visual.start, visual.end);
+					this.#yankAndDeleteRange(visual);
 				});
 				this.#clearSelection();
 				return;
@@ -1106,11 +1089,7 @@ export class VimEngine {
 				return nextIndex + 1;
 			case "s":
 				await this.#startInsertChange(["s"], () => {
-					const start = this.buffer.currentOffset();
-					this.register = {
-						kind: "char",
-						text: this.buffer.deleteOffsets(start, Math.min(this.buffer.getText().length, start + count)),
-					};
+					this.#deleteCharsForward(count);
 				});
 				return nextIndex + 1;
 			case "S":
@@ -1118,11 +1097,7 @@ export class VimEngine {
 				return nextIndex + 1;
 			case "x":
 				await this.#applyAtomicChange(["x"], () => {
-					const start = this.buffer.currentOffset();
-					this.register = {
-						kind: "char",
-						text: this.buffer.deleteOffsets(start, Math.min(this.buffer.getText().length, start + count)),
-					};
+					this.#deleteCharsForward(count);
 				});
 				return nextIndex + 1;
 			case "X":
@@ -1559,11 +1534,7 @@ export class VimEngine {
 		if (operator === "d") {
 			const range = this.#resolveMotionRange(motion);
 			await this.#applyAtomicChange(tokens, () => {
-				this.register = {
-					kind: range.linewise ? "line" : "char",
-					text: this.buffer.getText().slice(range.start, range.end),
-				};
-				this.buffer.deleteOffsets(range.start, range.end);
+				this.#yankAndDeleteRange(range);
 			});
 			return;
 		}
@@ -1571,16 +1542,28 @@ export class VimEngine {
 		if (operator === "c") {
 			const range = this.#resolveMotionRange(motion);
 			await this.#startInsertChange(tokens, () => {
-				this.register = {
-					kind: range.linewise ? "line" : "char",
-					text: this.buffer.getText().slice(range.start, range.end),
-				};
-				this.buffer.deleteOffsets(range.start, range.end);
+				this.#yankAndDeleteRange(range);
 			});
 			return;
 		}
 	}
 
+	#yankAndDeleteRange(range: { start: number; end: number; linewise: boolean }): void {
+		this.register = {
+			kind: range.linewise ? "line" : "char",
+			text: this.buffer.getText().slice(range.start, range.end),
+		};
+		this.buffer.deleteOffsets(range.start, range.end);
+	}
+
+	#deleteCharsForward(count: number): void {
+		const start = this.buffer.currentOffset();
+		this.register = {
+			kind: "char",
+			text: this.buffer.deleteOffsets(start, Math.min(this.buffer.getText().length, start + count)),
+		};
+	}
+
 	async #changeWholeLines(count: number, tokens: readonly string[]): Promise<void> {
 		await this.#startInsertChange(tokens, () => {
 			const start = this.buffer.cursor.line;

package/src/web/scrapers/crates-io.ts

@@ -1,19 +1,6 @@
 import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage } from "./types";
-
-/**
- * Check if content looks like HTML
- */
-function looksLikeHtml(content: string): boolean {
-	const trimmed = content.trim().toLowerCase();
-	return (
-		trimmed.startsWith("<!doctype") ||
-		trimmed.startsWith("<html") ||
-		trimmed.startsWith("<head") ||
-		trimmed.startsWith("<body")
-	);
-}
+import { buildResult, formatNumber, loadPage, looksLikeHtml } from "./types";
 
 /**
  * Handle crates.io URLs via API

package/src/web/scrapers/types.ts

@@ -283,3 +283,16 @@ export function getLocalizedText(value: LocalizedText, defaultLocale?: string):
 		value["en-US"] ?? value.en_US ?? value.en ?? Object.values(value).find(v => typeof v === "string") ?? undefined
 	);
 }
+
+/**
+ * Check if content looks like HTML by inspecting the leading tag.
+ */
+export function looksLikeHtml(content: string): boolean {
+	const trimmed = content.trim().toLowerCase();
+	return (
+		trimmed.startsWith("<!doctype") ||
+		trimmed.startsWith("<html") ||
+		trimmed.startsWith("<head") ||
+		trimmed.startsWith("<body")
+	);
+}

package/src/web/search/providers/base.ts

@@ -4,6 +4,19 @@ import type { SearchProviderId, SearchResponse } from "../types";
 export interface SearchParams {
 	query: string;
 	limit?: number;
+	/**
+	 * Temporal filter narrowing results to the specified time window.
+	 *
+	 * Providers MUST interpret this as a pure time filter. Providers MUST NOT
+	 * use recency as an implicit signal to change topic scope, content domain,
+	 * or ranking strategy. If a provider API couples temporal filtering with
+	 * other dimensions (e.g. Tavily's `topic=news`), the provider implementation
+	 * is responsible for decoupling them before calling the upstream API.
+	 *
+	 * Providers that do not support temporal filtering MUST ignore this field
+	 * silently; they MUST NOT approximate it by rewriting the query or altering
+	 * any other request parameter.
+	 */
 	recency?: "day" | "week" | "month" | "year";
 	systemPrompt: string;
 	signal?: AbortSignal;