@gajae-code/coding-agent 0.17.2 → 0.17.4

package/src/tools/bash.ts

@@ -66,10 +66,13 @@ import {
 } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
 import { formatToolWorkingDirectory, replaceTabs } from "./render-utils";
+import { steerFoldReasonLine, watchSteerForFold } from "./steer-fold";
 import { checkTmuxSelfInjection } from "./tmux-self-injection-guard";
 import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
+export { STEER_FOLD_GRACE_MS, steerFoldReasonLine } from "./steer-fold";
+
 function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string {
 	if (offsetBytes <= 0) return text;
 	let consumed = 0;
@@ -86,19 +89,6 @@ function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string
 import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
-/**
- * A user steer folds a running foreground bash call only after it has been
- * running at least this long. Shorter commands finish normally and the steer is
- * consumed at the ordinary tool boundary, so a quick `git status` never turns
- * into a background job plus a wake-up turn.
- */
-export const STEER_FOLD_GRACE_MS = 2_000;
-
-/** Model-facing line appended to a steer-folded background-start result. */
-export function steerFoldReasonLine(jobId: string): string {
-	return `Folded into background job ${jobId} because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`;
-}
-
 const BASH_ERROR_MAX_BYTES = 4096;
 const ARTIFACT_SAVE_DIAGNOSTIC_MAX_BYTES = 256;
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -481,12 +471,50 @@ export async function saveBashOriginalArtifactForTests(
 	return result.status === "saved" ? result.artifactId : undefined;
 }
 
+/**
+ * Model-declared activity metadata for the browser-backend routing contract
+ * (`browser.backend: aside`). When that contract routes a browser task through
+ * Bash, it requires the call to declare the activity structurally so consumers
+ * can project it without parsing the command text. The declaration is
+ * model-declared and schema-validated only: nothing here verifies that the
+ * command actually invokes Aside, and the executor never inspects `command`.
+ */
+export type BashActivityProvider = "aside";
+export type BashActivityMode = "repl" | "exec";
+export interface BashActivityDeclaration {
+	kind: "browser";
+	provider: BashActivityProvider;
+	mode: BashActivityMode;
+}
+
+const bashActivityDeclarationSchema = z
+	.object({
+		kind: z.literal("browser"),
+		provider: z.literal("aside"),
+		mode: z.enum(["repl", "exec"]),
+	})
+	.strict();
+
+/**
+ * Optional activity declaration. Anything that is not the exact supported
+ * shape is dropped rather than failing the call: the declaration is routing
+ * metadata, and a malformed value must never make an otherwise valid command
+ * unusable. Values are never coerced — `mode: "EXEC"` is dropped, not guessed.
+ */
+const optionalBashActivity = z
+	.preprocess(
+		value => (bashActivityDeclarationSchema.safeParse(value).success ? value : undefined),
+		bashActivityDeclarationSchema.optional(),
+	)
+	.describe("declare browser activity for the aside browser backend: repl or exec");
+
 const bashSchemaBase = z.object({
 	command: z.string().describe("command to execute"),
 	env: z.record(z.string().regex(BASH_ENV_NAME_PATTERN), z.string()).optional().describe("extra env vars"),
 	timeout: z.number().default(300).describe("timeout in seconds, NOT milliseconds (30 = 30s)").optional(),
 	cwd: z.string().describe("working directory").optional(),
 	pty: z.boolean().describe("run in pty mode").optional(),
+	activity: optionalBashActivity,
 });
 
 const bashSchemaWithAsync = bashSchemaBase.extend({
@@ -503,6 +531,8 @@ export interface BashToolInput {
 
 	async?: boolean;
 	pty?: boolean;
+	/** Accepted activity declaration, mirrored into {@link BashToolDetails.activity}. */
+	activity?: BashActivityDeclaration;
 }
 
 export interface BashToolDetails {
@@ -512,6 +542,8 @@ export interface BashToolDetails {
 	terminalId?: string;
 	/** Why the foreground wait was folded, when this result is a background-start after a fold. */
 	foldReason?: FoldReason;
+	/** The accepted model-declared activity declaration, when the call carried one. */
+	activity?: BashActivityDeclaration;
 	async?: {
 		state: "running" | "completed" | "failed";
 		jobId: string;
@@ -924,6 +956,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			notices?: readonly string[];
 			terminalId?: string;
 			artifactReferenceInBody?: boolean;
+			activity?: BashActivityDeclaration;
 		} = {},
 	): AgentToolResult<BashToolDetails> {
 		const shortArtifactInBody = !result.truncated && result.artifactId !== undefined;
@@ -947,6 +980,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (options.terminalId !== undefined) {
 			details.terminalId = options.terminalId;
 		}
+		if (options.activity !== undefined) {
+			details.activity = options.activity;
+		}
 		const resultBuilder = toolResult(details)
 			.text(outputText)
 			.truncationFromSummary(result, {
@@ -967,6 +1003,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			notices?: readonly string[];
 			terminalId?: string;
 			foldReason?: FoldReason;
+			activity?: BashActivityDeclaration;
 		} = {},
 	): AgentToolResult<BashToolDetails> {
 		const details: BashToolDetails = {
@@ -980,6 +1017,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
 		}
 		if (options.foldReason !== undefined) details.foldReason = options.foldReason;
+		if (options.activity !== undefined) details.activity = options.activity;
 		const lines: string[] = [];
 		const trimmedPreview = previewText.trimEnd();
 		if (trimmedPreview.length > 0) {
@@ -1019,6 +1057,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		onCompletion?: () => void;
 		/** Immutable attempt-scoped tool call id, when executed via a tool call. */
 		toolCallId?: string;
+		/** Accepted activity declaration, mirrored into job progress and result details. */
+		activity?: BashActivityDeclaration;
 	}): ManagedBashJobHandle {
 		const manager = this.#resolveOwnedJobManager();
 		if (!manager) {
@@ -1032,12 +1072,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				: options.command;
 		let latestText = "";
 		let backgrounded = options.startBackgrounded;
+		const activityDetails = options.activity === undefined ? {} : { activity: options.activity };
 		const runningDetails = (jobId: string): Record<string, unknown> | undefined =>
-			backgrounded ? { async: { state: "running", jobId, type: "bash" } } : undefined;
+			backgrounded ? { async: { state: "running", jobId, type: "bash" }, ...activityDetails } : undefined;
 		const completedDetails = (jobId: string): Record<string, unknown> | undefined =>
-			backgrounded ? { async: { state: "completed", jobId, type: "bash" } } : undefined;
+			backgrounded ? { async: { state: "completed", jobId, type: "bash" }, ...activityDetails } : undefined;
 		const failedDetails = (jobId: string): Record<string, unknown> | undefined =>
-			backgrounded ? { async: { state: "failed", jobId, type: "bash" } } : undefined;
+			backgrounded ? { async: { state: "failed", jobId, type: "bash" }, ...activityDetails } : undefined;
 		const completion = Promise.withResolvers<ManagedBashJobCompletion>();
 
 		const jobId = manager.register(
@@ -1088,6 +1129,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 						requestedTimeoutSec: options.requestedTimeoutSec,
 						notices: options.notices,
 						artifactReferenceInBody: true,
+						activity: options.activity,
 					});
 					const finalText = this.#extractTextResult(finalResult);
 					latestText = finalText;
@@ -1110,7 +1152,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					latestText = text;
 					await options.onUpdate?.({
 						content: [{ type: "text", text }],
-						details: backgrounded ? ((details ?? {}) as BashToolDetails) : {},
+						// Backgrounded frames carry the job details verbatim; a foreground
+						// frame has no job facts, but the activity declaration is per-call
+						// metadata and stays attached so partial results are self-describing.
+						details: backgrounded ? ((details ?? {}) as BashToolDetails) : (activityDetails as BashToolDetails),
 					});
 				},
 			},
@@ -1155,62 +1200,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
 
-	/**
-	 * Whether a queued user steer may fold the running foreground wait. Mirrors
-	 * the loop's steer admission: `busyPromptMode=queue` never admits a steer
-	 * into the busy run, so it never folds. `toolInterruptPolicy` is
-	 * deliberately NOT a gate: `finish_tools` means "do not kill the batch to
-	 * deliver a steer", and a fold kills nothing. It is the one way to deliver
-	 * the steer now AND let the command finish, so it applies under both
-	 * policies; the policy only decides what the loop does with sibling tools
-	 * after the fold returns. The auto-background setting is likewise not
-	 * consulted: like the chord, a steer fold is a user action.
-	 *
-	 * Fails closed: a session that cannot report newly admitted steering or
-	 * accept a fold request is not steer-foldable.
-	 */
-	#steerFoldEnabled(): boolean {
-		const { waitForUserSteering, requestForegroundBashBackground } = this.session;
-		if (!waitForUserSteering || !requestForegroundBashBackground) return false;
-		return this.session.settings.get("busyPromptMode") === "steer";
-	}
-
-	/**
-	 * Fold `adapter` on the first user steer that ARRIVES after the wait has run
-	 * for {@link STEER_FOLD_GRACE_MS} since `startedAt`. A steer already queued
-	 * when the wait starts, or one that arrives inside the grace window, never
-	 * folds: the command finishes normally and that steer is consumed at the
-	 * ordinary tool boundary. The watcher keeps observing so a later qualifying
-	 * steer still folds, and re-checks the gate at that moment so a
-	 * `busyPromptMode` change during the command is honored.
-	 * Returns a stop function; call it when the wait settles. No-op when steer
-	 * folding is gated off at start.
-	 */
-	#watchSteerForFold(adapter: FoldAdapter, startedAt: number): () => void {
-		if (!this.#steerFoldEnabled()) return () => {};
-		const waitForSteer = this.session.waitForUserSteering;
-		const requestFold = this.session.requestForegroundBashBackground;
-		if (!waitForSteer || !requestFold) return () => {};
-		const watch = new AbortController();
-		const observe = async (): Promise<void> => {
-			while (!watch.signal.aborted) {
-				await waitForSteer(watch.signal);
-				if (watch.signal.aborted) return;
-				if (Date.now() - startedAt < STEER_FOLD_GRACE_MS) continue;
-				if (!this.#steerFoldEnabled()) continue;
-				await requestFold("steer", adapter);
-				return;
-			}
-		};
-		observe().catch((error: unknown) => {
-			logger.warn("Steer-triggered fold failed", {
-				jobId: adapter.jobId,
-				error: error instanceof Error ? error.message : String(error),
-			});
-		});
-		return () => watch.abort();
-	}
-
 	/**
 	 * Race a managed job against the auto-background threshold, an explicit fold
 	 * (chord / SDK control / steer), and abort. A steer that arrives once the
@@ -1269,7 +1258,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		}
 
 		const stopSteerWatch =
-			backgroundRequest && foldAdapter ? this.#watchSteerForFold(foldAdapter, startedAt) : () => {};
+			backgroundRequest && foldAdapter
+				? watchSteerForFold(this.session, startedAt, fold => fold("steer", foldAdapter), foldAdapter.jobId)
+				: () => {};
 		try {
 			return await Promise.race(waiters);
 		} finally {
@@ -1571,9 +1562,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		notices: readonly string[],
 		signal: AbortSignal | undefined,
 		resolvedEnv: Record<string, string>,
+		activity: BashActivityDeclaration | undefined,
 	): Promise<AgentToolResult<BashToolDetails>> {
 		const result = await this.#runDirectMasterSpawn(command, commandCwd, timeoutMs, signal, resolvedEnv);
-		return this.#buildCompletedResult(result, timeoutSec, { requestedTimeoutSec, notices });
+		return this.#buildCompletedResult(result, timeoutSec, { requestedTimeoutSec, notices, activity });
 	}
 
 	/**
@@ -1723,6 +1715,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 
 			async: asyncRequested = false,
 			pty = false,
+			activity,
 		}: BashToolInput,
 		signal?: AbortSignal,
 		onUpdate?: AgentToolUpdateCallback<BashToolDetails>,
@@ -1767,6 +1760,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				pendingNotices,
 				signal,
 				resolvedEnv,
+				activity,
 			);
 		}
 
@@ -1792,6 +1786,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				onUpdate,
 				startBackgrounded: true,
 				toolCallId,
+				activity,
 			});
 			const jobGeneration = asyncManager.getJob(job.jobId)?.generation ?? job.jobId;
 			job.setBackgrounded(true);
@@ -1799,6 +1794,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
+				activity,
 			});
 		}
 
@@ -1845,6 +1841,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					managedForegroundSettled = true;
 				},
 				toolCallId,
+				activity,
 			});
 			const jobGeneration = ownedManager.getJob(job.jobId)?.generation ?? job.jobId;
 			if (startBackgrounded) {
@@ -1853,6 +1850,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
+					activity,
 				});
 			}
 			const backgroundRequest = Promise.withResolvers<FoldReason>();
@@ -1948,6 +1946,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 				foldReason: waitResult.reason,
+				activity,
 			});
 		}
 
@@ -2246,6 +2245,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 								requestedTimeoutSec,
 								notices: timeoutNotices,
 								terminalId: handle.terminalId,
+								activity,
 							});
 						}
 
@@ -2378,6 +2378,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					requestedTimeoutSec,
 					notices: bridgeNotices,
 					terminalId: handle.terminalId,
+					activity,
 				});
 			};
 
@@ -2419,7 +2420,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							bridgeCompletion.resolve({ kind: "completed", result });
 							await reportProgress(
 								finalText,
-								bridgeBackgrounded ? { async: { state: "completed", jobId, type: "bash" } } : undefined,
+								bridgeBackgrounded
+									? {
+											async: { state: "completed", jobId, type: "bash" },
+											...(activity === undefined ? {} : { activity }),
+										}
+									: undefined,
 							);
 							return finalText;
 						} catch (error) {
@@ -2429,7 +2435,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							bridgeCompletion.resolve({ kind: "failed", error });
 							await reportProgress(
 								message,
-								bridgeBackgrounded ? { async: { state: "failed", jobId, type: "bash" } } : undefined,
+								bridgeBackgrounded
+									? {
+											async: { state: "failed", jobId, type: "bash" },
+											...(activity === undefined ? {} : { activity }),
+										}
+									: undefined,
 							);
 							throw error;
 						} finally {
@@ -2556,6 +2567,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				notices: pendingNotices,
 				terminalId: handle.terminalId,
 				foldReason: bridgeWait.reason,
+				activity,
 			});
 		}
 
@@ -2640,6 +2652,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 										outcome = await controls.terminalCompletion;
 										const completed = this.#buildCompletedResult(outcome, timeoutSec, {
 											requestedTimeoutSec,
+											activity,
 										});
 										return this.#extractTextResult(completed);
 									} finally {
@@ -2707,6 +2720,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 									requestedTimeoutSec,
 									notices: pendingNotices,
 									foldReason: receipt.reason,
+									activity,
 								});
 								const outcome = controls.detachObserver(
 									interactiveResultFromText(this.#extractTextResult(started)),
@@ -2722,7 +2736,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							resolveForegroundObserver: () => "already-settled",
 						};
 						const unregisterPtyFold = this.session.registerForegroundFoldParticipant?.(ptyFoldAdapter);
-						const stopPtySteerWatch = this.#watchSteerForFold(ptyFoldAdapter, ptyStartedAt);
+						const stopPtySteerWatch = watchSteerForFold(
+							this.session,
+							ptyStartedAt,
+							fold => fold("steer", ptyFoldAdapter),
+							ptyFoldAdapter.jobId,
+						);
 						ptyFoldUnregister = () => {
 							stopPtySteerWatch();
 							unregisterPtyFold?.();
@@ -2790,6 +2809,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return this.#buildCompletedResult(result, timeoutSec, {
 			requestedTimeoutSec,
 			notices: pendingNotices,
+			activity,
 		});
 	}
 }

package/src/tools/fetch.ts

@@ -49,6 +49,7 @@ const FETCH_DEFAULT_MAX_LINES = 300;
 // Convertible document types handled by markit.
 const CONVERTIBLE_MIMES = new Set([
 	"application/pdf",
+	"application/x-pdf",
 	"application/msword",
 	"application/vnd.ms-powerpoint",
 	"application/vnd.ms-excel",
@@ -228,17 +229,52 @@ function normalizeMime(contentType: string): string {
 	return contentType.split(";")[0].trim().toLowerCase();
 }
 
+// Bound both parsing work and decoded filename size to a single modest header.
+function getDispositionFilename(header: string): string | undefined {
+	if (header.length > 8192 || /[\x00-\x1f\x7f]/.test(header.replaceAll("\t", ""))) return undefined;
+	const separator = header.indexOf(";");
+	if (separator < 0) return undefined;
+	const parameter = /;[ \t]*([!#$%&'*+.^_`|~\w-]+)[ \t]*=[ \t]*(?:"((?:[^"\\]|\\.)*)"|([!#$%&'*+.^_`|~\w-]+))[ \t]*/y;
+	let offset = separator;
+	let plain: string | undefined;
+	let extended: string | undefined;
+	const seen = new Set<string>();
+	while (offset < header.length) {
+		parameter.lastIndex = offset;
+		const match = parameter.exec(header);
+		if (!match) return undefined;
+		offset = parameter.lastIndex;
+		const name = match[1].toLowerCase();
+		if (name !== "filename" && name !== "filename*") continue;
+		// Duplicate filename parameters are ambiguous, not an ordering override.
+		if (seen.has(name)) return undefined;
+		seen.add(name);
+		const value = match[2] === undefined ? match[3] : match[2].replace(/\\(.)/g, "$1");
+		if (name === "filename") {
+			if (value) plain = value;
+			continue;
+		}
+		// RFC 8187 ext-value: only UTF-8 is supported; quoted ext-values are invalid.
+		const encoded =
+			match[2] === undefined ? /^UTF-8'[A-Za-z0-9-]*'((?:[!#$&+.^_`|~\w-]|%[\da-fA-F]{2})*)$/i.exec(value) : null;
+		if (!encoded) continue;
+		try {
+			const decoded = decodeURIComponent(encoded[1]);
+			if (decoded && !/[\x00-\x1f\x7f]/.test(decoded)) extended = decoded;
+		} catch {
+			// Invalid UTF-8 or percent encoding must not escape classification.
+		}
+	}
+	return extended ?? plain;
+}
+
 /**
  * Get extension from URL or Content-Disposition
  */
 function getExtensionHint(url: string, contentDisposition?: string): string {
-	// Try Content-Disposition filename first
 	if (contentDisposition) {
-		const match = contentDisposition.match(/filename[*]?=["']?([^"';\n]+)/i);
-		if (match) {
-			const ext = path.extname(match[1]).toLowerCase();
-			if (ext) return ext;
-		}
+		const filename = getDispositionFilename(contentDisposition);
+		if (filename !== undefined) return path.extname(filename).toLowerCase();
 	}
 
 	// Fall back to URL path
@@ -251,21 +287,25 @@ function getExtensionHint(url: string, contentDisposition?: string): string {
 	return "";
 }
 
+function isGenericMimeType(mime: string): boolean {
+	return (
+		mime.length === 0 || mime === "application/octet-stream" || mime === "binary/octet-stream" || mime === "unknown"
+	);
+}
+
 /**
  * Check if content type is convertible via markit.
  */
 function isConvertible(mime: string, extensionHint: string): boolean {
-	if (CONVERTIBLE_MIMES.has(mime)) return true;
-	if (mime === "application/octet-stream" && CONVERTIBLE_EXTENSIONS.has(extensionHint)) return true;
-	if (CONVERTIBLE_EXTENSIONS.has(extensionHint)) return true;
-	return false;
+	return (
+		CONVERTIBLE_MIMES.has(mime) ||
+		(CONVERTIBLE_EXTENSIONS.has(extensionHint) && (extensionHint !== ".pdf" || isGenericMimeType(mime)))
+	);
 }
 
 function resolveImageMimeType(mime: string, extensionHint: string): string | null {
 	if (mime.startsWith("image/")) return mime;
-	const shouldUseExtensionHint =
-		mime.length === 0 || mime === "application/octet-stream" || mime === "binary/octet-stream" || mime === "unknown";
-	if (!shouldUseExtensionHint) return null;
+	if (!isGenericMimeType(mime)) return null;
 	return IMAGE_MIME_BY_EXTENSION.get(extensionHint) ?? null;
 }
 
@@ -741,15 +781,60 @@ async function renderUrl(
 	const { finalUrl, content: rawContent } = response;
 	const mime = normalizeMime(response.contentType);
 	const extHint = getExtensionHint(finalUrl);
+	let isPdf =
+		mime === "application/pdf" || mime === "application/x-pdf" || (extHint === ".pdf" && isGenericMimeType(mime));
+
+	// Raw PDF inspection is explicit; never substitute PDF bytes for failed text extraction.
+	if (raw && isPdf) {
+		const output = finalizeOutput(rawContent);
+		return {
+			url,
+			finalUrl,
+			contentType: mime,
+			method: "raw",
+			content: output.content,
+			fetchedAt,
+			truncated: output.truncated,
+			notes,
+		};
+	}
 
-	const imageMimeType = resolveImageMimeType(mime, extHint);
+	// Classify generic downloads from the bounded binary response before dispatch.
+	// Both image rendering and document conversion reuse these bytes.
+	const dispositionBinary =
+		!raw && isGenericMimeType(mime)
+			? response.buffer
+				? { ok: true as const, buffer: response.buffer, contentDisposition: response.contentDisposition }
+				: await fetchBinary(finalUrl, timeout, signal)
+			: undefined;
+	if (dispositionBinary && !dispositionBinary.ok) {
+		notes.push(dispositionBinary.error ? `Binary fetch failed: ${dispositionBinary.error}` : "Binary fetch failed");
+		return {
+			url,
+			finalUrl,
+			contentType: mime,
+			method: "failed",
+			content: "",
+			fetchedAt,
+			truncated: false,
+			notes,
+		};
+	}
+	const effectiveExt = dispositionBinary?.ok
+		? getExtensionHint(finalUrl, dispositionBinary.contentDisposition)
+		: extHint;
+	isPdf =
+		mime === "application/pdf" ||
+		mime === "application/x-pdf" ||
+		(effectiveExt === ".pdf" && isGenericMimeType(mime));
+	const imageMimeType = isPdf ? undefined : resolveImageMimeType(mime, effectiveExt);
 	let skipConvertibleBinaryRetry = false;
 	if (imageMimeType) {
 		if (!isInlineImageMimeTypeSupported(imageMimeType)) {
 			notes.push(
 				`Image MIME type ${imageMimeType} is unsupported for inline model serialization; returning text metadata only`,
 			);
-			const shouldTryConvertibleFallback = isConvertible(mime, extHint);
+			const shouldTryConvertibleFallback = isConvertible(mime, effectiveExt);
 			if (shouldTryConvertibleFallback) {
 				notes.push("Attempting binary conversion fallback for unsupported image MIME type");
 			} else {
@@ -757,7 +842,7 @@ async function renderUrl(
 			}
 			skipConvertibleBinaryRetry = !shouldTryConvertibleFallback;
 		} else {
-			const binary = await fetchBinary(finalUrl, timeout, signal);
+			const binary = dispositionBinary ?? (await fetchBinary(finalUrl, timeout, signal));
 			if (binary.ok) {
 				notes.push("Fetched image binary");
 				const conversionExtension = getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
@@ -868,10 +953,10 @@ async function renderUrl(
 	}
 
 	// Step 3: Handle convertible binary files (PDF, DOCX, etc.)
-	if (!skipConvertibleBinaryRetry && isConvertible(mime, extHint)) {
-		const binary = await fetchBinary(finalUrl, timeout, signal);
+	if (!skipConvertibleBinaryRetry && (isPdf || isConvertible(mime, effectiveExt))) {
+		const binary = dispositionBinary ?? (await fetchBinary(finalUrl, timeout, signal));
 		if (binary.ok) {
-			const ext = getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
+			const ext = isPdf ? ".pdf" : getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
 			const converted = await convertWithMarkit(binary.buffer, ext, timeout, signal);
 			if (converted.ok) {
 				// Any non-empty markit conversion is preferable to a raw-bytes
@@ -902,6 +987,18 @@ async function renderUrl(
 		} else {
 			notes.push("Binary fetch failed");
 		}
+		if (isPdf) {
+			return {
+				url,
+				finalUrl,
+				contentType: mime,
+				method: "failed",
+				content: "",
+				fetchedAt,
+				truncated: false,
+				notes,
+			};
+		}
 	}
 
 	// Step 4: Handle non-HTML text content
@@ -1066,7 +1163,7 @@ async function renderUrl(
 				if (binary.ok) {
 					const ext = getExtensionHint(docUrl, binary.contentDisposition);
 					const converted = await convertWithMarkit(binary.buffer, ext, timeout, signal);
-					if (converted.ok && converted.content.trim().length > htmlResult.content.length) {
+					if (converted.ok && converted.content.trim().length > (ext === ".pdf" ? 0 : htmlResult.content.length)) {
 						notes.push(`Extracted and converted document: ${docUrl}`);
 						const output = finalizeOutput(converted.content);
 						return {
@@ -1082,6 +1179,8 @@ async function renderUrl(
 					}
 					if (!converted.ok && converted.error) {
 						notes.push(`markit conversion failed: ${converted.error}`);
+					} else if (converted.ok && !converted.content.trim()) {
+						notes.push("markit conversion produced no usable output");
 					}
 				} else if (binary.error) {
 					notes.push(`Binary fetch failed: ${binary.error}`);