@gajae-code/coding-agent 0.9.1 → 0.9.3

package/src/session/session-manager.ts

@@ -45,8 +45,6 @@ import {
 	MemoryBlobStore,
 	parseBlobRef,
 	ResidentBlobMissingError,
-	resolveImageData,
-	resolveImageDataUrl,
 	resolveResidentImageDataSync,
 	resolveResidentImageDataUrlSync,
 	resolveTextBlobSync,
@@ -973,47 +971,46 @@ export async function loadEntriesFromFile(
 }
 
 /**
- * Resolve blob references in loaded entries, restoring both session image blocks and persisted
- * provider image URLs back to the inline data expected by downstream transports. Mutates entries in place.
+ * Convert legacy persisted blob references in loaded entries into resident sentinels.
+ * Images then materialize lazily at provider/display/export chokepoints instead of
+ * pinning every historical base64 string for the lifetime of a resumed session.
  */
 function hasImageUrl(value: unknown): value is { image_url: string | { url?: string } } {
 	return typeof value === "object" && value !== null && "image_url" in value;
 }
 
-async function resolvePersistedBlobRefs(value: unknown, blobStore: BlobStore, key?: string): Promise<void> {
+function residentizePersistedBlobRefs(value: unknown, key?: string): void {
 	if (Array.isArray(value)) {
-		await Promise.all(value.map(item => resolvePersistedBlobRefs(item, blobStore, key)));
+		for (const item of value) residentizePersistedBlobRefs(item, key);
 		return;
 	}
 
 	if (typeof value !== "object" || value === null) return;
 
 	if (isImageBlock(value) && isBlobRef(value.data)) {
-		value.data = await resolveImageData(blobStore, value.data);
+		value.data = residentBlobSentinel("imageData", value.data) as unknown as string;
 	}
 
 	if (hasImageUrl(value)) {
 		if (typeof value.image_url === "string" && isBlobRef(value.image_url)) {
-			value.image_url = await resolveImageDataUrl(blobStore, value.image_url);
+			value.image_url = residentBlobSentinel("imageUrl", value.image_url) as unknown as string;
 		} else if (
 			typeof value.image_url === "object" &&
 			value.image_url !== null &&
 			typeof value.image_url.url === "string" &&
 			isBlobRef(value.image_url.url)
 		) {
-			value.image_url.url = await resolveImageDataUrl(blobStore, value.image_url.url);
+			value.image_url.url = residentBlobSentinel("imageUrl", value.image_url.url) as unknown as string;
 		}
 	}
 
-	await Promise.all(
-		Object.entries(value).map(async ([childKey, item]) => {
-			if (childKey === "data" && typeof item === "string" && isBlobRef(item) && key !== TEXT_CONTENT_KEY) {
-				(value as Record<string, unknown>)[childKey] = await resolveImageDataUrl(blobStore, item);
-				return;
-			}
-			await resolvePersistedBlobRefs(item, blobStore, childKey);
-		}),
-	);
+	for (const [childKey, item] of Object.entries(value)) {
+		if (childKey === "data" && typeof item === "string" && isBlobRef(item) && key !== TEXT_CONTENT_KEY) {
+			(value as Record<string, unknown>)[childKey] = residentBlobSentinel("imageUrl", item);
+			continue;
+		}
+		residentizePersistedBlobRefs(item, childKey);
+	}
 }
 
 /**
@@ -1035,28 +1032,13 @@ async function runWithConcurrency(tasks: Array<() => Promise<void>>, limit: numb
 	await Promise.all(Array.from({ length: workerCount }, () => worker()));
 }
 
-async function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void> {
+async function resolveBlobRefsInEntries(entries: FileEntry[], _blobStore: BlobStore): Promise<void> {
 	const tasks: Array<() => Promise<void>> = [];
 
 	for (const entry of entries) {
 		if (entry.type === "session") continue;
-
-		let contentArray: unknown[] | undefined;
-		if (entry.type === "message" && "content" in entry.message && Array.isArray(entry.message.content)) {
-			contentArray = entry.message.content;
-		} else if (entry.type === "custom_message" && Array.isArray(entry.content)) {
-			contentArray = entry.content;
-		}
-
 		tasks.push(async () => {
-			if (contentArray) {
-				for (const block of contentArray) {
-					if (isImageBlock(block) && isBlobRef(block.data)) {
-						block.data = await resolveImageData(blobStore, block.data);
-					}
-				}
-			}
-			await resolvePersistedBlobRefs(entry, blobStore);
+			residentizePersistedBlobRefs(entry);
 		});
 	}
 
@@ -1314,6 +1296,33 @@ function containsResidentSentinel(value: unknown, seen = new WeakSet<object>()):
 	return false;
 }
 
+function containsResidentImageSentinel(value: unknown, seen = new WeakSet<object>()): boolean {
+	if (value === null || value === undefined || typeof value !== "object") return false;
+	if (isResidentBlobSentinel(value)) return value.kind === "imageUrl" || value.kind === "imageData";
+	if (seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) return value.some(item => containsResidentImageSentinel(item, seen));
+	for (const child of Object.values(value)) {
+		if (containsResidentImageSentinel(child, seen)) return true;
+	}
+	return false;
+}
+
+function collectResidentImageRefs(value: unknown, refs: Set<string>, seen = new WeakSet<object>()): void {
+	if (value === null || value === undefined || typeof value !== "object") return;
+	if (isResidentBlobSentinel(value)) {
+		if (value.kind === "imageUrl" || value.kind === "imageData") refs.add(value.ref);
+		return;
+	}
+	if (seen.has(value)) return;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) collectResidentImageRefs(item, refs, seen);
+		return;
+	}
+	for (const child of Object.values(value)) collectResidentImageRefs(child, refs, seen);
+}
+
 /**
  * Recursively truncate large strings in an object for session persistence.
  * - Truncates any oversized string fields (key-agnostic)
@@ -4148,6 +4157,22 @@ export class SessionManager {
 		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
+	getResidentImageBytes(): number {
+		const refs = new Set<string>();
+		for (const entry of this.#fileEntries) collectResidentImageRefs(entry, refs);
+		let bytes = 0;
+		for (const ref of refs) {
+			const hash = parseBlobRef(ref);
+			if (!hash) continue;
+			try {
+				bytes += fs.statSync(path.join(this.#residentImageBlobStore.dir, hash)).size;
+			} catch (err) {
+				if (!isEnoent(err)) throw err;
+			}
+		}
+		return bytes;
+	}
+
 	/**
 	 * Get the most recent model role from the current session path.
 	 * Returns undefined if no model change has been recorded.
@@ -4571,11 +4596,14 @@ export class SessionManager {
 		}
 		this.#materializedEntriesCachePopulateCount++;
 		const resolvedTextBlobCache = new Map<string, string>();
-		const materializedEntries = this.#fileEntries
-			.filter((e): e is SessionEntry => e.type !== "session")
-			.map(entry => materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
-		this.#materializedEntriesCache = materializedEntries;
-		this.#materializedEntriesRevision = this.#entryRevision;
+		const sourceEntries = this.#fileEntries.filter((e): e is SessionEntry => e.type !== "session");
+		const materializedEntries = sourceEntries.map(entry =>
+			materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache),
+		);
+		if (!sourceEntries.some(entry => containsResidentImageSentinel(entry))) {
+			this.#materializedEntriesCache = materializedEntries;
+			this.#materializedEntriesRevision = this.#entryRevision;
+		}
 		return materializedEntries;
 	}
 

package/src/system-prompt.ts

@@ -507,7 +507,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 				? loadSkills({ ...skillsSettings, cwd: resolvedCwd }).then(result => result.skills)
 				: Promise.resolve([]);
 
-	const [resolvedCustomPrompt, resolvedAppendPrompt, systemPromptCustomization, contextFiles, skills, workspaceTree] =
+	const [resolvedCustomPrompt, resolvedAppendPrompt, systemPromptCustomization, contextFiles, , workspaceTree] =
 		await Promise.all([
 			withDeadline(
 				"customPrompt",
@@ -581,11 +581,9 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		description: tools?.get(name)?.description ?? "",
 	}));
 
-	// Filter skills for the rendered system prompt:
-	// - require the `read` tool so the model can actually fetch skill content;
-	// - drop skills with frontmatter `hide: true` (still loadable via skill:// and /skill:<name>).
-	const hasRead = tools?.has("read");
-	const filteredSkills = hasRead ? skills.filter(skill => skill.hide !== true) : [];
+	// Runtime skills are discovered by `skill_discovery` and loaded narrowly through
+	// `skill`; do not dump the full custom skill catalog into the core prompt.
+	const filteredSkills: Skill[] = [];
 
 	const effectiveSystemPromptCustomization = dedupePromptSource(systemPromptCustomization, [
 		resolvedCustomPrompt,

package/src/tools/bash-interactive.ts

@@ -12,7 +12,6 @@ import {
 } from "@gajae-code/tui";
 import { sanitizeText } from "@gajae-code/utils";
 import type { Terminal as XtermTerminalType } from "@xterm/headless";
-import xterm from "@xterm/headless";
 import { Settings } from "../config/settings";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import type { Theme } from "../modes/theme/theme";
@@ -32,8 +31,6 @@ function normalizeCaptureChunk(chunk: string): string {
 	return sanitizeWithOptionalSixelPassthrough(normalized, sanitizeText);
 }
 
-const XtermTerminal = xterm.Terminal;
-
 function normalizeInputForPty(data: string, applicationCursorKeysMode: boolean): string {
 	const kitty = parseKittySequence(data);
 	if (kitty?.eventType === 3) {
@@ -113,6 +110,7 @@ class BashInteractiveOverlayComponent implements Component {
 		private readonly command: string,
 		private readonly uiTheme: Theme,
 		private readonly getTerminalRows: () => number,
+		XtermTerminal: typeof XtermTerminalType,
 	) {
 		this.#terminal = new XtermTerminal({
 			cols: 120,
@@ -305,10 +303,17 @@ export async function runInteractiveBashPty(
 		headBytes: resolveOutputSinkHeadBytes(settings),
 		maxColumns: resolveOutputMaxColumns(settings),
 	});
+	const { default: xterm } = await import("@xterm/headless");
+	const XtermTerminal = xterm.Terminal;
 	const result = await ui.custom<BashInteractiveResult>(
 		(tui, uiTheme, _keybindings, done) => {
 			const session = new PtySession();
-			const component = new BashInteractiveOverlayComponent(options.command, uiTheme, () => tui.terminal.rows);
+			const component = new BashInteractiveOverlayComponent(
+				options.command,
+				uiTheme,
+				() => tui.terminal.rows,
+				XtermTerminal,
+			);
 			component.setSession(session);
 			let finished = false;
 			const finalize = (run: PtyRunResult) => {

package/src/tools/browser/readable.ts

@@ -1,5 +1,5 @@
 import { Readability } from "@mozilla/readability";
-import { parseHTML } from "linkedom";
+import { parseHtmlLazy } from "../../utils/linkedom";
 import { htmlToBasicMarkdown } from "../../web/scrapers/types";
 
 export type ReadableFormat = "text" | "markdown";
@@ -31,7 +31,7 @@ export async function extractReadableFromHtml(
 	url: string,
 	format: ReadableFormat,
 ): Promise<ReadableResult | null> {
-	const { document } = parseHTML(html);
+	const { document } = await parseHtmlLazy(html);
 
 	// --- Primary: Readability article extraction ---
 	const article = new Readability(document).parse();

package/src/tools/fetch.ts

@@ -5,7 +5,6 @@ import type { ImageContent, TextContent } from "@gajae-code/ai";
 import { htmlToMarkdown } from "@gajae-code/natives";
 import { type Component, Text } from "@gajae-code/tui";
 import { $which, ptree, truncate } from "@gajae-code/utils";
-import { parseHTML } from "linkedom";
 import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme, theme } from "../modes/theme/theme";
@@ -15,6 +14,7 @@ import { DEFAULT_MAX_BYTES, truncateHead } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { parseHtmlLazy } from "../utils/linkedom";
 import { ensureTool } from "../utils/tools-manager";
 import { INSANE_NOTES, tryInsaneFetch } from "../web/insane/bridge";
 import { validatePublicHttpUrl, validatePublicHttpUrlForInsane } from "../web/insane/url-guard";
@@ -483,9 +483,9 @@ function cleanFeedText(text: string): string {
 /**
  * Parse RSS/Atom feed to markdown
  */
-function parseFeedToMarkdown(content: string, maxItems = 10): string {
+async function parseFeedToMarkdown(content: string, maxItems = 10): Promise<string> {
 	try {
-		const doc = parseHTML(content).document;
+		const doc = (await parseHtmlLazy(content)).document;
 
 		// Try RSS
 		const channel = doc.querySelector("channel");
@@ -1026,7 +1026,7 @@ async function renderUrl(
 	}
 
 	if (isFeed || (isXml && (rawContent.includes("<rss") || rawContent.includes("<feed")))) {
-		const parsed = parseFeedToMarkdown(rawContent);
+		const parsed = await parseFeedToMarkdown(rawContent);
 		const output = finalizeOutput(parsed);
 		return {
 			url,
@@ -1119,7 +1119,7 @@ async function renderUrl(
 			const altResult = await loadPage(resolved, { timeout, signal });
 			if (altResult.ok && altResult.content.trim().length > 200) {
 				notes.push(`Used feed alternate: ${resolved}`);
-				const parsed = parseFeedToMarkdown(altResult.content);
+				const parsed = await parseFeedToMarkdown(altResult.content);
 				const output = finalizeOutput(parsed);
 				return {
 					url,

package/src/tools/index.ts

@@ -56,6 +56,7 @@ import { reportFindingTool } from "./review";
 import { SearchTool } from "./search";
 import { SearchToolBm25Tool } from "./search-tool-bm25";
 import { SkillTool } from "./skill";
+import { SkillDiscoveryTool } from "./skill-discovery";
 import { loadSshTool } from "./ssh";
 import { SubagentTool } from "./subagent";
 import { TelegramSendTool } from "./telegram-send";
@@ -95,6 +96,7 @@ export * from "./review";
 export * from "./search";
 export * from "./search-tool-bm25";
 export * from "./skill";
+export * from "./skill-discovery";
 export * from "./ssh";
 export * from "./subagent";
 export * from "./telegram-send";
@@ -411,6 +413,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	todo_write: s => new TodoWriteTool(s),
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
+	skill_discovery: SkillDiscoveryTool.createIf,
 	telegram_send: TelegramSendTool.createIf,
 	write: s => new WriteTool(s),
 	skill: SkillTool.createIf,
@@ -570,6 +573,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "search_tool_bm25") return discoveryActive;
 		if (name === "calc") return session.settings.get("calc.enabled");
 		if (name === "skill") return session.settings.get("skill.enabled");
+		if (name === "skill_discovery") return session.settings.get("skill.enabled");
 		if (name === "browser") return session.settings.get("browser.enabled");
 		if (name === "computer") return isComputerCallable(session);
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");

package/src/tools/skill-discovery.ts

@@ -0,0 +1,73 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import { prompt, untilAborted } from "@gajae-code/utils";
+import * as z from "zod/v4";
+import { discoverRuntimeSkills, type RuntimeSkillDiscoveryCandidate } from "../extensibility/runtime-skill-discovery";
+import skillDiscoveryDescription from "../prompts/tools/skill-discovery.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const skillDiscoverySchema = z
+	.object({
+		query: z
+			.string()
+			.optional()
+			.describe("words to match against skill name, description, source, or use conditions"),
+		source: z.enum(["all", "project", "user"]).default("all").optional().describe("skill source scope to search"),
+		limit: z.number().min(1).max(50).default(20).optional().describe("maximum results"),
+	})
+	.strict();
+
+export type SkillDiscoveryToolInput = z.infer<typeof skillDiscoverySchema>;
+
+export interface SkillDiscoveryToolDetails {
+	candidates: RuntimeSkillDiscoveryCandidate[];
+	count: number;
+}
+
+export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema, SkillDiscoveryToolDetails> {
+	readonly name = "skill_discovery";
+	readonly label = "SkillDiscovery";
+	readonly summary = "Discover project and user runtime skills by thin metadata";
+	readonly loadMode = "essential";
+	readonly description: string;
+	readonly parameters = skillDiscoverySchema;
+	readonly strict = true;
+
+	readonly #session: ToolSession;
+
+	constructor(session: ToolSession) {
+		this.#session = session;
+		this.description = prompt.render(skillDiscoveryDescription);
+	}
+
+	#getRuntimeSkillPolicy() {
+		return {
+			...this.#session.settings.getGroup("skills"),
+			disabledExtensions: this.#session.settings.get("disabledExtensions"),
+		};
+	}
+
+	static createIf(session: ToolSession): SkillDiscoveryTool | null {
+		if (session.settings.get("skill.enabled") === false) return null;
+		return new SkillDiscoveryTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		input: SkillDiscoveryToolInput,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<SkillDiscoveryToolDetails>> {
+		return untilAborted(signal, async () => {
+			const candidates = await discoverRuntimeSkills({
+				cwd: this.#session.cwd,
+				query: input.query,
+				source: input.source ?? "all",
+				limit: input.limit,
+				policy: this.#getRuntimeSkillPolicy(),
+			});
+			return {
+				content: [{ type: "text", text: JSON.stringify({ candidates, count: candidates.length }, null, 2) }],
+				details: { candidates, count: candidates.length },
+			};
+		});
+	}
+}

package/src/tools/skill.ts

@@ -4,25 +4,28 @@
  * Lets the agent hand off to another available skill in the current turn. The
  * callee's SKILL.md is dispatched through the same custom-message path used by
  * `/skill:<name>` typing, as a user-attribution message delivered same-turn
- * (without `deliverAs: "nextTurn"`). Before dispatch, the tool calls
- * `gjc state <caller> handoff --to <callee>` in-process via the state-runtime
- * function so caller and callee mode-states plus `skill-active-state.json`
- * transition atomically.
+ * (without `deliverAs: "nextTurn"`). When the caller is one of the canonical
+ * workflow skills, the tool first runs the native state handoff so workflow
+ * mode-state and `skill-active-state.json` transition atomically. Runtime
+ * project/user skills have no native workflow mode-state, so they are dispatched
+ * directly and tracked by the prompt observer instead.
  *
- * Chaining is refused unless the caller's `current_phase` is in
- * `{complete, completed, handoff, failed, cancelled, canceled, inactive}`. The
- * agent declares readiness either by writing `current_phase: "handoff"` to its
- * mode-state or by running the handoff verb directly.
+ * Canonical workflow chaining is refused unless the caller's `current_phase` is
+ * in `{complete, completed, handoff, failed, cancelled, canceled, inactive}`.
+ * The agent declares readiness either by writing `current_phase: "handoff"` to
+ * its mode-state or by running the handoff verb directly.
  */
 
 import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
 import { prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { resolveSubskillActivationForSkillInvocation } from "../extensibility/gjc-plugins";
+import { findRuntimeSkillByName } from "../extensibility/runtime-skill-discovery";
 import { buildSkillPromptMessage } from "../extensibility/skills";
 import { runNativeStateCommand } from "../gjc-runtime/state-runtime";
 import skillDescription from "../prompts/tools/skill.md" with { type: "text" };
 import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
+import { isCanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 import type { ToolSession } from ".";
 import { ToolError } from "./tool-errors";
 
@@ -64,6 +67,13 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 		this.description = prompt.render(skillDescription);
 	}
 
+	#getRuntimeSkillPolicy() {
+		return {
+			...this.#session.settings.getGroup("skills"),
+			disabledExtensions: this.#session.settings.get("disabledExtensions"),
+		};
+	}
+
 	static createIf(session: ToolSession): SkillTool | null {
 		// The tool can only chain when the session can deliver the same-turn
 		// custom message. Without `sendCustomMessage` (e.g. minimal tool
@@ -110,16 +120,22 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 				);
 			}
 
-			const skill = skills.find(s => s.name === requestedName);
+			const skill =
+				skills.find(s => s.name === requestedName) ??
+				(await findRuntimeSkillByName(this.#session.cwd, requestedName, this.#getRuntimeSkillPolicy()));
 			if (!skill) {
 				const available = skills.map(s => s.name).sort();
-				const hint = available.length > 0 ? ` Available: ${available.join(", ")}` : "";
+				const hint =
+					available.length > 0
+						? ` Available: ${available.join(", ")}. Use skill_discovery to find project/user runtime skills.`
+						: " Use skill_discovery to find project/user runtime skills.";
 				throw new ToolError(`skill tool: unknown skill "${requestedName}".${hint}`);
 			}
 
-			// Phase guard + atomic handoff. Only runs when transitioning between
-			// distinct skills (same-skill recursion was already refused above).
-			if (activeSkill) {
+			// Phase guard + atomic native handoff only apply to canonical workflow
+			// skills. Runtime project/user skills do not have a native mode-state,
+			// so there is no `gjc state <skill>` command to run for them.
+			if (activeSkill && isCanonicalGjcWorkflowSkill(activeSkill)) {
 				const phase = (this.#session.getActiveSkillPhase?.() ?? "running").trim().toLowerCase();
 				if (!TERMINAL_PHASES.has(phase)) {
 					throw new ToolError(

package/src/utils/linkedom.ts

@@ -0,0 +1,14 @@
+type LinkedomModule = typeof import("linkedom");
+
+type ParseHtml = LinkedomModule["parseHTML"];
+
+let parseHtml: ParseHtml | undefined;
+let linkedomImport: Promise<LinkedomModule> | undefined;
+
+export async function parseHtmlLazy(markup: string): Promise<ReturnType<ParseHtml>> {
+	if (!parseHtml) {
+		linkedomImport ??= import("linkedom");
+		parseHtml = (await linkedomImport).parseHTML;
+	}
+	return parseHtml(markup);
+}

package/src/utils/pasted-image-path.ts

@@ -1,12 +1,12 @@
 /**
  * Resolve pasted editor text to an image file path.
  *
- * Terminals insert a shell-escaped filesystem path when a file is drag-dropped
- * onto them (e.g. macOS `Screenshot\ 2026-07-07\ at\ 11.06.38 PM.png`, where
- * the visible "space" before AM/PM is U+202F and stays unescaped). When the
- * entire paste is a single path to an existing image file, the interactive
- * editor attaches the image and inserts an `[image N]` placeholder instead of
- * leaving the raw path in the prompt.
+ * Some terminal/clipboard integrations paste a temporary filesystem path after a
+ * copied image is pasted into the editor (for example `/tmp/clipboard-...png`).
+ * Only those recognized clipboard temp files are auto-attached and replaced with
+ * an `[image N] source="/path"` reference so the model receives both the image
+ * payload and the raw temp file path. Ordinary image paths remain literal prompt
+ * text; users attach saved files explicitly with `@path/to/image.png`.
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const IMAGE_FILE_EXTENSION_PATTERN = /\.(?:png|jpe?g|gif|webp)$/i;
+const CLIPBOARD_TEMP_BASENAME_PATTERN = /^clipboard-\d{4}-\d{2}-\d{2}-\d{6}-[A-Za-z0-9-]+\.(?:png|jpe?g|gif|webp)$/i;
 
 export interface DecodePastedPathOptions {
 	/**
@@ -150,16 +151,25 @@ function hasSupportedImageMagic(filePath: string): boolean {
 	}
 }
 
+function isRecognizedClipboardTempPath(filePath: string): boolean {
+	const resolved = path.resolve(filePath);
+	const tempRoot = path.resolve(os.tmpdir());
+	if (resolved !== tempRoot && !resolved.startsWith(`${tempRoot}${path.sep}`)) return false;
+	return CLIPBOARD_TEMP_BASENAME_PATTERN.test(path.basename(resolved));
+}
+
 /**
- * Returns the resolved path when the whole pasted text is a single path to an
- * existing image file (verified by extension AND content signature),
- * otherwise `undefined` (the paste is inserted as text).
+ * Returns the resolved path when the whole pasted text is a recognized clipboard
+ * temp path to an existing image file, otherwise `undefined` (the paste is
+ * inserted as text). Arbitrary saved image paths are not auto-attached here;
+ * users attach them explicitly with `@path/to/image.png`.
  */
 export function resolvePastedImagePath(text: string, options?: ResolvePastedImagePathOptions): string | undefined {
 	const candidate = decodePastedPathCandidate(text, options);
 	if (!candidate || !IMAGE_FILE_EXTENSION_PATTERN.test(candidate)) return undefined;
 
 	const resolved = path.resolve(options?.cwd ?? process.cwd(), candidate);
+	if (!isRecognizedClipboardTempPath(resolved)) return undefined;
 	try {
 		if (!fs.statSync(resolved).isFile()) return undefined;
 	} catch {
@@ -168,3 +178,7 @@ export function resolvePastedImagePath(text: string, options?: ResolvePastedImag
 	if (!hasSupportedImageMagic(resolved)) return undefined;
 	return resolved;
 }
+
+export function formatPastedImageReference(placeholder: string, imagePath: string): string {
+	return `${placeholder} source=${JSON.stringify(imagePath)}`;
+}

package/src/web/scrapers/arxiv.ts

@@ -1,4 +1,4 @@
-import { parseHTML } from "linkedom";
+import { parseHtmlLazy } from "../../utils/linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
 import { convertWithMarkit, fetchBinary } from "./utils";
@@ -31,7 +31,7 @@ export const handleArxiv: SpecialHandler = async (
 		if (!result.ok) return null;
 
 		// Parse the Atom feed response
-		const doc = parseHTML(result.content).document;
+		const doc = (await parseHtmlLazy(result.content)).document;
 		const entry = doc.querySelector("entry");
 
 		if (!entry) return null;

package/src/web/scrapers/go-pkg.ts

@@ -1,5 +1,5 @@
 import { tryParseJson } from "@gajae-code/utils";
-import { parseHTML } from "linkedom";
+import { parseHtmlLazy } from "../../utils/linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, htmlToBasicMarkdown, loadPage } from "./types";
 
@@ -97,7 +97,7 @@ export const handleGoPkg: SpecialHandler = async (
 			});
 		}
 
-		const doc = parseHTML(pageResult.content).document;
+		const doc = (await parseHtmlLazy(pageResult.content)).document;
 
 		// Extract actual module path from breadcrumb or header
 		const breadcrumb = doc.querySelector(".go-Breadcrumb");

package/src/web/scrapers/iacr.ts

@@ -1,4 +1,4 @@
-import { parseHTML } from "linkedom";
+import { parseHtmlLazy } from "../../utils/linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
 import { convertWithMarkit, fetchBinary } from "./utils";
@@ -30,7 +30,7 @@ export const handleIacr: SpecialHandler = async (
 
 		if (!result.ok) return null;
 
-		const doc = parseHTML(result.content).document;
+		const doc = (await parseHtmlLazy(result.content)).document;
 
 		// Extract metadata from the page
 		const title =

package/src/web/scrapers/readthedocs.ts

@@ -1,7 +1,7 @@
 /**
  * Read the Docs handler for web-fetch
  */
-import { parseHTML } from "linkedom";
+import { parseHtmlLazy } from "../../utils/linkedom";
 import { buildResult, htmlToBasicMarkdown, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 export const handleReadTheDocs: SpecialHandler = async (
@@ -39,7 +39,7 @@ export const handleReadTheDocs: SpecialHandler = async (
 	}
 
 	// Parse HTML
-	const root = parseHTML(result.content).document;
+	const root = (await parseHtmlLazy(result.content)).document;
 
 	// Extract main content from common Read the Docs selectors
 	let mainContent =