@oh-my-pi/pi-coding-agent 15.10.0 → 15.10.2

package/src/task/render.ts

@@ -6,18 +6,20 @@
  */
 import path from "node:path";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Container, Text } from "@oh-my-pi/pi-tui";
+import { Container, Markdown, Text } from "@oh-my-pi/pi-tui";
 import { formatNumber } from "@oh-my-pi/pi-utils";
 import { settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { formatContextUsage } from "../modes/components/status-line/context-thresholds";
-import type { Theme } from "../modes/theme/theme";
+import { shimmerEnabled, shimmerText } from "../modes/theme/shimmer";
+import { getMarkdownTheme, type Theme } from "../modes/theme/theme";
 import {
 	formatBadge,
 	formatDuration,
 	formatMoreItems,
 	formatStatusIcon,
 	replaceTabs,
+	type ToolUIStatus,
 	truncateToWidth,
 } from "../tools/render-utils";
 import {
@@ -28,7 +30,8 @@ import {
 	type ReportFindingDetails,
 	type SubmitReviewDetails,
 } from "../tools/review";
-import { Ellipsis, Hasher, type RenderCache, renderStatusLine } from "../tui";
+import { framedBlock, renderStatusLine } from "../tui";
+import { repairDoubleEncodedJsonString } from "./repair-args";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import type { AgentProgress, SingleResult, TaskItem, TaskParams, TaskToolDetails } from "./types";
 
@@ -506,28 +509,20 @@ function formatOutputInline(data: unknown, theme: Theme, maxWidth = 80): string
  * preview. The args stream in token by token, so the array grows over time and
  * trailing entries may be partially parsed — every field access is defensive.
  */
-function renderTaskItemLines(
-	tasks: TaskItem[] | undefined,
-	contPrefix: string,
-	expanded: boolean,
-	theme: Theme,
-): string[] {
+function renderTaskItemLines(tasks: TaskItem[] | undefined, expanded: boolean, theme: Theme): string[] {
 	const items = tasks ?? [];
 	if (items.length === 0) return [];
 
-	const branch = theme.fg("dim", theme.tree.branch);
-	const last = theme.fg("dim", theme.tree.last);
+	const bullet = theme.fg("dim", "•");
 	const cap = expanded ? items.length : Math.min(items.length, 12);
 	const truncated = cap < items.length;
 
 	const lines: string[] = [];
 	for (let i = 0; i < cap; i++) {
 		const task = items[i] as Partial<TaskItem> | undefined;
-		const isLastLine = !truncated && i === items.length - 1;
-		const connector = isLastLine ? last : branch;
 		const rawId = task?.id?.trim();
 		const idLabel = rawId ? formatTaskId(rawId) : `#${i + 1}`;
-		let line = `${contPrefix}${connector} ${theme.fg("accent", theme.bold(idLabel))}`;
+		let line = `${bullet} ${theme.fg("accent", theme.bold(idLabel))}`;
 		const desc = task?.description?.trim();
 		if (desc) {
 			line += `: ${theme.fg("muted", truncateToWidth(replaceTabs(desc), 64))}`;
@@ -535,11 +530,42 @@ function renderTaskItemLines(
 		lines.push(line);
 	}
 	if (truncated) {
-		lines.push(`${contPrefix}${last} ${theme.fg("dim", formatMoreItems(items.length - cap, "agent"))}`);
+		lines.push(`${bullet} ${theme.fg("dim", formatMoreItems(items.length - cap, "agent"))}`);
 	}
 	return lines;
 }
 
+/**
+ * Build the shared-context section (the `# Goal / # Constraints` background
+ * passed to every subagent). Rendered in both the streaming call preview and
+ * the merged result frame so the brief stays visible for the whole task
+ * lifecycle — not just until the first progress snapshot replaces the call view.
+ */
+type TaskRenderSection = { lines: string[] };
+type ContextSectionRenderer = (width: number) => TaskRenderSection;
+
+// Default output-block layout is: left border + one-cell content inset + right
+// border. Render markdown at that inner width so the output block does not need
+// to rewrap already-rendered context lines.
+const CONTEXT_FRAME_INSET = 3;
+
+function contextMarkdownWidth(frameWidth: number): number {
+	return Math.max(1, frameWidth - CONTEXT_FRAME_INSET);
+}
+
+function createContextSectionRenderer(args: TaskParams | undefined, theme: Theme): ContextSectionRenderer | undefined {
+	// `renderResult` receives the raw tool args (unlike `renderCall`, which is
+	// fed through `repairTaskParams`), so undo any per-field double-encoding here
+	// too. The repair is idempotent on already-clean text.
+	const context = repairDoubleEncodedJsonString(args?.context ?? "").trim();
+	if (!context) return undefined;
+
+	const markdown = new Markdown(context, 0, 0, getMarkdownTheme(), {
+		color: text => theme.fg("muted", text),
+	});
+	return width => ({ lines: markdown.render(contextMarkdownWidth(width)) });
+}
+
 /**
  * Render the tool call arguments.
  */
@@ -548,44 +574,34 @@ export function renderCall(
 	options: RenderResultOptions & { renderContext?: { hasResult?: boolean } },
 	theme: Theme,
 ): Component {
-	const lines: string[] = [];
-	lines.push(renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme));
-
-	const context = (args.context ?? "").trim();
-	const hasContext = context.length > 0;
-	const branch = theme.fg("dim", theme.tree.branch);
-	const last = theme.fg("dim", theme.tree.last);
-	const vertical = theme.fg("dim", theme.tree.vertical);
 	const showIsolated = "isolated" in args && args.isolated === true;
-	const taskCount = args.tasks?.length ?? 0;
-
-	if (hasContext) {
-		lines.push(` ${branch} ${theme.fg("dim", "Context")}`);
-		const contextLines = context.split("\n").map(line => {
-			const content = line ? theme.fg("muted", replaceTabs(line)) : "";
-			return ` ${vertical}  ${content}`;
-		});
-		lines.push(...contextLines);
-	}
-
-	// `Tasks` is the last child unless the isolation flag follows it.
-	const tasksIsLast = !showIsolated;
-	const tasksPrefix = tasksIsLast ? last : branch;
-	lines.push(` ${tasksPrefix} ${theme.fg("dim", "Tasks")} ${theme.fg("muted", `(${taskCount})`)}`);
-	const tasksContPrefix = tasksIsLast ? "    " : ` ${vertical}  `;
-	// The per-task preview list only exists to surface dispatched agents while
-	// the call args stream in. Once a result snapshot exists, `renderResult`
-	// draws the same agents as progress/result lines (id + description), so
-	// emitting the preview here would render every task twice.
-	if (!options.renderContext?.hasResult) {
-		lines.push(...renderTaskItemLines(args.tasks, tasksContPrefix, options.expanded, theme));
-	}
-
-	if (showIsolated) {
-		lines.push(` ${last} ${theme.fg("dim", "Isolated")}: ${theme.fg("muted", "true")}`);
-	}
+	const header = renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme);
+	const contextSectionRenderer = createContextSectionRenderer(args, theme);
+	return framedBlock(theme, width => {
+		const sections: Array<{ label?: string; lines: string[]; separator?: boolean }> = [];
+
+		if (contextSectionRenderer) sections.push(contextSectionRenderer(width));
+
+		// The per-task preview list only exists to surface dispatched agents while
+		// the call args stream in. Once a result snapshot exists, `renderResult`
+		// draws the same agents as progress/result lines, so showing the Tasks
+		// section here would just repeat the count the result frame already shows.
+		if (!options.renderContext?.hasResult) {
+			sections.push({
+				separator: true,
+				lines: renderTaskItemLines(args.tasks, options.expanded, theme),
+			});
+		}
 
-	return new Text(lines.join("\n"), 0, 0);
+		return {
+			header,
+			headerMeta: showIsolated ? "isolated" : undefined,
+			sections,
+			state: "pending",
+			borderColor: "borderMuted",
+			width,
+		};
+	});
 }
 
 /**
@@ -593,14 +609,13 @@ export function renderCall(
  */
 function renderAgentProgress(
 	progress: AgentProgress,
-	isLast: boolean,
+	prefix: string,
+	continuePrefix: string,
 	expanded: boolean,
 	theme: Theme,
 	spinnerFrame?: number,
 ): string[] {
 	const lines: string[] = [];
-	const prefix = isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch);
-	const continuePrefix = isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `;
 
 	const icon = getStatusIcon(progress.status, theme, spinnerFrame);
 	const iconColor =
@@ -614,11 +629,23 @@ function renderAgentProgress(
 	const description = progress.description?.trim();
 	const displayId = formatTaskId(progress.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
-	let statusLine = `${prefix} ${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
+	const indent = prefix ? `${prefix} ` : "";
+	let statusLine: string;
+	if (progress.status === "running") {
+		const bullet = theme.fg("accent", "•");
+		const name = theme.fg("accent", description ? theme.bold(displayId) : displayId);
+		statusLine = `${indent}${bullet} ${name}`;
+		if (description) {
+			const desc = shimmerEnabled() ? shimmerText(description, theme) : theme.fg("accent", description);
+			statusLine += `${theme.fg("accent", ":")} ${desc}`;
+		}
+	} else {
+		statusLine = `${indent}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
+	}
 
 	// Show retry-blocked badge so the parent immediately sees that a child
 	// is sleeping on a provider 429, not silently progressing. Wins over the
-	// generic running spinner because "we're waiting on a quota window" is
+	// generic running marker because "we're waiting on a quota window" is
 	// the operationally meaningful state.
 	if (progress.retryState && progress.status === "running") {
 		statusLine += ` ${formatBadge("retrying", "warning", theme)}`;
@@ -867,10 +894,14 @@ function renderFindings(
 /**
  * Render final result for a single agent.
  */
-function renderAgentResult(result: SingleResult, isLast: boolean, expanded: boolean, theme: Theme): string[] {
+function renderAgentResult(
+	result: SingleResult,
+	prefix: string,
+	continuePrefix: string,
+	expanded: boolean,
+	theme: Theme,
+): string[] {
 	const lines: string[] = [];
-	const prefix = isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch);
-	const continuePrefix = isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `;
 
 	const { warning: missingCompleteWarning, rest: outputWithoutWarning } = extractMissingYieldWarning(result.output);
 	const aborted = result.aborted ?? false;
@@ -899,7 +930,7 @@ function renderAgentResult(result: SingleResult, isLast: boolean, expanded: bool
 	const description = result.description?.trim();
 	const displayId = formatTaskId(result.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
-	let statusLine = `${prefix} ${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)} ${formatBadge(
+	let statusLine = `${prefix ? `${prefix} ` : ""}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)} ${formatBadge(
 		statusText,
 		iconColor,
 		theme,
@@ -1043,101 +1074,123 @@ export function renderResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: TaskToolDetails },
 	options: RenderResultOptions,
 	theme: Theme,
+	args?: TaskParams,
 ): Component {
 	const fallbackText = result.content.find(c => c.type === "text")?.text ?? "";
 	const details = result.details;
+	const contextSectionRenderer = createContextSectionRenderer(args, theme);
 
 	if (!details) {
 		const text = result.content.find(c => c.type === "text")?.text || "";
-		return new Text(theme.fg("dim", truncateToWidth(text, 100)), 0, 0);
+		const header = renderStatusLine({ icon: "success", title: "Task" }, theme);
+		return framedBlock(theme, width => ({
+			header,
+			sections: [
+				...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
+				...(text ? [{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] }] : []),
+			],
+			state: "success",
+			borderColor: "borderMuted",
+			width,
+		}));
 	}
 
-	let cached: RenderCache | undefined;
+	const hasResults = Boolean(details.results && details.results.length > 0);
+	const aborted = hasResults && details.results.some(r => r.aborted);
+	const failed = hasResults && details.results.some(r => !r.aborted && r.exitCode !== 0);
+	const mergeFailed = hasResults && details.results.some(r => !r.aborted && r.exitCode === 0 && Boolean(r.error));
+	const isError = aborted || failed;
+	const agentCount = hasResults ? details.results.length : (details.progress?.length ?? 0);
+	const icon: ToolUIStatus = options.isPartial ? "running" : isError ? "error" : mergeFailed ? "warning" : "success";
+	const header = renderStatusLine(
+		{
+			icon,
+			title: "Task",
+			meta: agentCount > 0 ? [`${agentCount} ${agentCount === 1 ? "agent" : "agents"}`] : undefined,
+		},
+		theme,
+	);
 
-	return {
-		render(width) {
-			const { expanded, isPartial, spinnerFrame } = options;
-			const key = new Hasher()
-				.bool(expanded)
-				.bool(isPartial)
-				.u32(spinnerFrame ?? 0)
-				.u32(width)
-				.digest();
-			if (cached?.key === key) return cached.lines;
-
-			const lines: string[] = [];
-
-			const shouldRenderProgress =
-				Boolean(details.progress && details.progress.length > 0) && (isPartial || details.results.length === 0);
-			if (shouldRenderProgress && details.progress) {
-				details.progress.forEach((progress, i) => {
-					const isLast = i === details.progress!.length - 1;
-					lines.push(...renderAgentProgress(progress, isLast, expanded, theme, spinnerFrame));
-				});
-			} else if (details.results && details.results.length > 0) {
-				details.results.forEach((res, i) => {
-					const isLast = i === details.results.length - 1;
-					lines.push(...renderAgentResult(res, isLast, expanded, theme));
-				});
-
-				const abortedCount = details.results.filter(r => r.aborted).length;
-				const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
-				const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
-				const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
-				let summary = `${theme.fg("dim", "Total:")} `;
-				if (abortedCount > 0) {
-					summary += theme.fg("error", `${abortedCount} aborted`);
-					if (successCount > 0 || mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-				}
-				if (successCount > 0) {
-					summary += theme.fg("success", `${successCount} succeeded`);
-					if (mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-				}
-				if (mergeFailedCount > 0) {
-					summary += theme.fg("warning", `${mergeFailedCount} merge failed`);
-					if (failCount > 0) summary += theme.sep.dot;
-				}
-				if (failCount > 0) {
-					summary += theme.fg("error", `${failCount} failed`);
-				}
-				summary += `${theme.sep.dot}${theme.fg("dim", formatDuration(details.totalDurationMs))}`;
-				lines.push(summary);
-			}
+	return framedBlock(theme, width => {
+		const { expanded, isPartial, spinnerFrame } = options;
+		const lines: string[] = [];
 
-			if (lines.length === 0) {
-				const text = fallbackText.trim() ? fallbackText : "No results";
-				const result = [theme.fg("dim", truncateToWidth(text, width))];
-				cached = { key, lines: result };
-				return result;
-			}
+		const shouldRenderProgress =
+			Boolean(details.progress && details.progress.length > 0) && (isPartial || details.results.length === 0);
+		if (shouldRenderProgress && details.progress) {
+			details.progress.forEach(progress => {
+				lines.push(...renderAgentProgress(progress, "", "  ", expanded, theme, spinnerFrame));
+			});
+		} else if (details.results && details.results.length > 0) {
+			details.results.forEach(res => {
+				lines.push(...renderAgentResult(res, "", "  ", expanded, theme));
+			});
 
-			if (fallbackText.trim()) {
-				const summaryLines = fallbackText.split("\n");
-				const markerIndex = summaryLines.findIndex(
-					line =>
-						line.includes("<system-notification>") ||
-						line.startsWith("Applied patches:") ||
-						line.startsWith("No changes to apply."),
-				);
-				if (markerIndex >= 0) {
-					const extra = summaryLines.slice(markerIndex);
-					for (const line of extra) {
-						if (!line.trim()) continue;
-						lines.push(theme.fg("dim", line));
-					}
+			const abortedCount = details.results.filter(r => r.aborted).length;
+			const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
+			const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
+			const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
+			const summaryParts: string[] = [];
+			if (abortedCount > 0) summaryParts.push(theme.fg("error", `${abortedCount} aborted`));
+			if (successCount > 0) summaryParts.push(theme.fg("success", `${successCount} succeeded`));
+			if (mergeFailedCount > 0) summaryParts.push(theme.fg("warning", `${mergeFailedCount} merge failed`));
+			if (failCount > 0) summaryParts.push(theme.fg("error", `${failCount} failed`));
+			summaryParts.push(theme.fg("dim", formatDuration(details.totalDurationMs)));
+			// Wrap the run summary in the theme's bracket glyphs (dim chrome, colored
+			// counts) to match the bash tool's `[Wall: … | Exit: …]` footer.
+			lines.push(
+				theme.fg("dim", theme.format.bracketLeft) +
+					summaryParts.join(theme.fg("dim", theme.sep.dot)) +
+					theme.fg("dim", theme.format.bracketRight),
+			);
+		}
+
+		const state = isPartial ? "running" : isError ? "error" : mergeFailed ? "warning" : "success";
+		const borderColor = isError ? "error" : "borderMuted";
+
+		if (lines.length === 0) {
+			const text = fallbackText.trim() ? fallbackText : "No results";
+			return {
+				header,
+				sections: [
+					...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
+					{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] },
+				],
+				state,
+				borderColor,
+				width,
+			};
+		}
+
+		if (fallbackText.trim()) {
+			const summaryLines = fallbackText.split("\n");
+			const markerIndex = summaryLines.findIndex(
+				line =>
+					line.includes("<system-notification>") ||
+					line.startsWith("Applied patches:") ||
+					line.startsWith("No changes to apply."),
+			);
+			if (markerIndex >= 0) {
+				const extra = summaryLines.slice(markerIndex);
+				for (const line of extra) {
+					if (!line.trim()) continue;
+					lines.push(theme.fg("dim", line));
 				}
 			}
+		}
 
-			const indented = lines.map(line =>
-				line.length > 0 ? truncateToWidth(`   ${line}`, width, Ellipsis.Omit) : "",
-			);
-			cached = { key, lines: indented };
-			return indented;
-		},
-		invalidate() {
-			cached = undefined;
-		},
-	};
+		while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+		return {
+			header,
+			sections: [
+				...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
+				...(lines.length > 0 ? [{ separator: true, lines }] : []),
+			],
+			state,
+			borderColor,
+			width,
+		};
+	});
 }
 
 function isTaskToolDetails(value: unknown): value is TaskToolDetails {
@@ -1149,13 +1202,23 @@ function isTaskToolDetails(value: unknown): value is TaskToolDetails {
 	);
 }
 
+// Nested subagent snapshots sit one or more levels below the frame border, so
+// they keep tree guides to convey depth (the parent prepends its own continue
+// prefix). Only the top-level agent list drops guides (the frame is its box).
+function nestedMarkers(isLast: boolean, theme: Theme): { prefix: string; continuePrefix: string } {
+	return {
+		prefix: isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch),
+		continuePrefix: isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `,
+	};
+}
+
 function renderNestedTaskResults(detailsList: TaskToolDetails[], expanded: boolean, theme: Theme): string[] {
 	const lines: string[] = [];
 	for (const details of detailsList) {
 		if (!details.results || details.results.length === 0) continue;
 		details.results.forEach((result, index) => {
-			const isLast = index === details.results.length - 1;
-			lines.push(...renderAgentResult(result, isLast, expanded, theme));
+			const { prefix, continuePrefix } = nestedMarkers(index === details.results.length - 1, theme);
+			lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
 		});
 	}
 	return lines;
@@ -1177,16 +1240,16 @@ function renderNestedTaskTree(
 		const hasResults = Boolean(details.results && details.results.length > 0);
 		if (hasResults) {
 			details.results.forEach((result, index) => {
-				const isLast = index === details.results.length - 1;
-				lines.push(...renderAgentResult(result, isLast, expanded, theme));
+				const { prefix, continuePrefix } = nestedMarkers(index === details.results.length - 1, theme);
+				lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
 			});
 			continue;
 		}
 		const inflight = details.progress;
 		if (inflight && inflight.length > 0) {
 			inflight.forEach((prog, index) => {
-				const isLast = index === inflight.length - 1;
-				lines.push(...renderAgentProgress(prog, isLast, expanded, theme, spinnerFrame));
+				const { prefix, continuePrefix } = nestedMarkers(index === inflight.length - 1, theme);
+				lines.push(...renderAgentProgress(prog, prefix, continuePrefix, expanded, theme, spinnerFrame));
 			});
 		}
 	}
@@ -1207,4 +1270,5 @@ subprocessToolRegistry.register<TaskToolDetails>("task", {
 export const taskToolRenderer = {
 	renderCall,
 	renderResult,
+	mergeCallAndResult: true,
 };

package/src/tools/archive-reader.ts

@@ -1,5 +1,9 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 import { inflateSync, strFromU8 } from "fflate";
 
+import { formatBytes } from "./render-utils";
 import { ToolError } from "./tool-errors";
 
 export type ArchiveFormat = "zip" | "tar" | "tar.gz";
@@ -123,11 +127,21 @@ function getArchiveFormatFromPath(filePath: string): ArchiveFormat | undefined {
 	return undefined;
 }
 
+export function formatArchiveEntryLines(entries: readonly ArchiveDirectoryEntry[]): string[] {
+	return entries.map(entry => {
+		if (entry.isDirectory) return `${entry.name}/`;
+
+		const sizeSuffix = entry.size > 0 ? ` (${formatBytes(entry.size)})` : "";
+		return `${entry.name}${sizeSuffix}`;
+	});
+}
+
 const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 const ZIP_CENTRAL_DIRECTORY_HEADER_SIGNATURE = 0x02014b50;
 const ZIP64_EOCD_SIGNATURE = 0x06064b50;
 const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
 const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_DATA_DESCRIPTOR_SIGNATURE = 0x08074b50;
 const ZIP_EOCD_MIN_LENGTH = 22;
 const ZIP_EOCD_MAX_COMMENT_LENGTH = 0xffff;
 const ZIP64_EOCD_LOCATOR_LENGTH = 20;
@@ -167,6 +181,37 @@ function readUInt32LE(bytes: Uint8Array, offset: number): number {
 	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
 }
 
+function bytesMatchAscii(bytes: Uint8Array, offset: number, value: string): boolean {
+	if (bytes.byteLength < offset + value.length) return false;
+	for (let index = 0; index < value.length; index++) {
+		if (bytes[offset + index] !== value.charCodeAt(index)) return false;
+	}
+	return true;
+}
+
+export function sniffArchiveFormat(bytes: Uint8Array): ArchiveFormat | undefined {
+	if (bytes.byteLength >= 4) {
+		const signature = readUInt32LE(bytes, 0);
+		if (
+			signature === ZIP_LOCAL_FILE_HEADER_SIGNATURE ||
+			signature === ZIP_EOCD_SIGNATURE ||
+			signature === ZIP_DATA_DESCRIPTOR_SIGNATURE
+		) {
+			return "zip";
+		}
+	}
+
+	if (bytes.byteLength >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) {
+		return "tar.gz";
+	}
+
+	if (bytesMatchAscii(bytes, 257, "ustar")) {
+		return "tar";
+	}
+
+	return undefined;
+}
+
 function readUInt64LEAsNumber(bytes: Uint8Array, offset: number): number {
 	const value = readUInt32LE(bytes, offset) + readUInt32LE(bytes, offset + 4) * ZIP_UINT32_RANGE;
 	if (!Number.isSafeInteger(value)) {
@@ -627,3 +672,22 @@ export async function openArchive(filePath: string): Promise<ArchiveReader> {
 		format === "zip" ? await readZipEntries(filePath) : await readTarEntries(await Bun.file(filePath).bytes());
 	return new ArchiveReader(format, entries);
 }
+
+export async function listArchiveRoot(
+	bytes: Uint8Array,
+	format: ArchiveFormat,
+	opts: { limit?: number } = {},
+): Promise<string> {
+	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-archive-"));
+	const tempPath = path.join(tempDir, `payload.${format}`);
+	try {
+		await Bun.write(tempPath, bytes);
+		const archive = await openArchive(tempPath);
+		const entries = archive.listDirectory("");
+		const limitedEntries = opts.limit !== undefined && opts.limit > 0 ? entries.slice(0, opts.limit) : entries;
+		const lines = formatArchiveEntryLines(limitedEntries);
+		return lines.length > 0 ? lines.join("\n") : "(empty archive directory)";
+	} finally {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	}
+}