@lelouchhe/webagent 0.8.0 → 0.10.0

package/lib/config.js

@@ -20,7 +20,7 @@ export const ConfigSchema = z.object({
         image_upload: z.number().int().positive().default(10_485_760), // 10 MB
         file_upload: z.number().int().positive().default(52_428_800), // 50 MB — non-image attachments
         cancel_timeout: z.number().int().nonnegative().default(10_000), // 10s; 0 disables
-        recent_paths: z.number().int().nonnegative().default(10), // /new menu display limit; 0 = show all
+        recent_paths: z.number().int().nonnegative().default(10), // /new + path-picker display limit; 0 = show all
         recent_paths_ttl: z.number().int().nonnegative().default(30), // days before auto-cleanup; 0 = keep forever
     })
         .default({
@@ -40,35 +40,6 @@ export const ConfigSchema = z.object({
         vapid_subject: "mailto:noreply@example.com",
         global_visibility_suppression: true,
     }),
-    // [title] — title generation sub-session configuration.
-    //
-    // `models` is an array of case-insensitive substring patterns. When the
-    // title sub-session is created, we look at the model list the agent
-    // reports (ACP `availableModels`) and pick the first model whose id
-    // matches any pattern in order. Match → call `setConfigOption` with
-    // that model id; no match → skip the call and inherit the agent's
-    // default model (`currentModelId`).
-    //
-    // Default list targets the cheap/fast tier across major providers:
-    //   - "haiku"      → Anthropic (claude-haiku-*)
-    //   - "flash-lite" → Google Gemini (gemini-*-flash-lite)  [must precede "flash"]
-    //   - "nano"       → OpenAI (gpt-*-nano), Gemini Nano
-    //   - "mini"       → OpenAI (gpt-*-mini, 4o-mini), Mistral
-    //   - "flash"      → Google Gemini (gemini-*-flash)
-    //   - "lite"       → Cohere, generic
-    //
-    // Set `models = []` to disable substring matching entirely and always
-    // inherit the agent's default model. To pin one specific model, pass a
-    // single-element array: `models = ["claude-haiku-4.5"]`.
-    title: z
-        .object({
-        models: z
-            .array(z.string())
-            .default(["haiku", "flash-lite", "nano", "mini", "flash", "lite"]),
-    })
-        .default({
-        models: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
-    }),
     // [debug] — frontend log level.
     // level ∈ off | debug | info | warn | error. Default "off".
     // Users can override per page-load via `?debug=<level>` in the URL,
@@ -86,7 +57,7 @@ export const ConfigSchema = z.object({
         unprocessed_ttl_days: z.number().int().nonnegative().default(30),
     })
         .default({ unprocessed_ttl_days: 30 }),
-    // [share] — public read-only session share links.
+    // [share] — public read-only task share links.
     // Default: disabled. Dogfood manually flips `enabled = true` after
     // CF Access bypass + Rate Limiting are configured. See docs/share.md.
     //   enabled        — master kill switch; when false, all share routes

package/lib/event-handler.js

@@ -4,45 +4,56 @@ import { isAutopilotMode } from "./mode-bucket.js";
 const ailog = log.scope("attachment-interceptor");
 const plog = log.scope("push");
 const clog = log.scope("cancel");
-function handleConnected(event, sessions, config) {
+function handleConnected(event, tasks, config) {
     event.cancelTimeout = config.cancelTimeout;
     event.recentPathsLimit = config.recentPathsLimit;
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive check
     if (event.agent)
-        sessions.agentInfo = event.agent;
+        tasks.agentInfo = event.agent;
 }
-function handleConfigLikeEvent(event, sessions) {
-    sessions.recordConfigOptions(event.sessionId, event.configOptions);
+function handleConfigLikeEvent(event, tasks) {
+    tasks.recordConfigOptions(event.taskId, event.configOptions);
 }
-function handleMessageChunk(event, sessions) {
-    sessions.flushThinkingBuffer(event.sessionId);
-    sessions.appendAssistant(event.sessionId, event.text);
-    sessions.state.patch(event.sessionId, {
+function handleMessageChunk(event, tasks) {
+    tasks.flushThinkingBuffer(event.taskId);
+    tasks.appendAssistant(event.taskId, event.text);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: true, thinking: false } },
     });
 }
-function handleThoughtChunk(event, sessions) {
-    sessions.flushAssistantBuffer(event.sessionId);
-    sessions.appendThinking(event.sessionId, event.text);
-    sessions.state.patch(event.sessionId, {
+function handleThoughtChunk(event, tasks) {
+    tasks.flushAssistantBuffer(event.taskId);
+    tasks.appendThinking(event.taskId, event.text);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: true } },
     });
 }
-function handleToolCall(event, sessions, store) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handleToolCall(event, tasks, store) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         id: event.id,
         title: event.title,
         kind: event.kind,
         rawInput: event.rawInput,
     }, { from_ref: "agent" });
 }
-function handlePlan(event, sessions, store) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handleUsageUpdate(event, tasks) {
+    tasks.state.patch(event.taskId, {
+        runtime: {
+            contextUsage: {
+                used: event.used,
+                size: event.size,
+                ...(event.cost !== undefined ? { cost: event.cost } : {}),
+            },
+        },
+    });
+}
+function handlePlan(event, tasks, store) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: {
             streaming: { assistant: false, thinking: false },
             plan: event.entries.length > 0 &&
@@ -51,14 +62,14 @@ function handlePlan(event, sessions, store) {
                 : null,
         },
     });
-    store.saveEvent(event.sessionId, event.type, { entries: event.entries }, { from_ref: "agent" });
+    store.saveEvent(event.taskId, event.type, { entries: event.entries }, { from_ref: "agent" });
 }
-function performAutoApprove(event, opt, sessions, store, bridge, sseManager, broadcastRequest) {
+function performAutoApprove(event, opt, tasks, store, bridge, sseManager, broadcastRequest) {
     bridge.resolvePermission(event.requestId, opt.optionId);
-    sessions.pendingPermissions.delete(event.requestId);
-    sessions.syncPendingPermissions(event.sessionId);
+    tasks.pendingPermissions.delete(event.requestId);
+    tasks.syncPendingPermissions(event.taskId);
     const optionName = opt.label ?? opt.optionId;
-    store.saveEvent(event.sessionId, "permission_response", {
+    store.saveEvent(event.taskId, "permission_response", {
         requestId: event.requestId,
         optionName,
         denied: false,
@@ -67,23 +78,23 @@ function performAutoApprove(event, opt, sessions, store, bridge, sseManager, bro
         sseManager.broadcast(event);
     sseManager.broadcast({
         type: "permission_response",
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         requestId: event.requestId,
         optionName,
         denied: false,
     });
 }
-function maybeAutoApprovePermission(event, sessions, store, bridge, sseManager) {
-    const mode = store.getSession(event.sessionId)?.mode ?? "";
+function maybeAutoApprovePermission(event, tasks, store, bridge, sseManager) {
+    const mode = store.getTask(event.taskId)?.mode ?? "";
     if (!isAutopilotMode(mode))
         return false;
     const opt = event.options.find((o) => o.kind === "allow_once");
     if (!opt)
         return false;
-    performAutoApprove(event, opt, sessions, store, bridge, sseManager, true);
+    performAutoApprove(event, opt, tasks, store, bridge, sseManager, true);
     return true;
 }
-function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManager, config) {
+function maybeAutoApproveAttachmentRead(event, tasks, store, bridge, sseManager, config) {
     // Plan §1.4 — async attachment-read auto-approve runs *after* the
     // permission_request has already been broadcast (so the UI shows it
     // briefly), then if the request matches we follow up with a
@@ -95,7 +106,7 @@ function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManag
     if (!opt)
         return;
     void shouldAutoApproveAttachmentRead({
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         toolKind: event.toolKind,
         toolName: event.toolName,
         locations: event.locations,
@@ -110,132 +121,197 @@ function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManag
             return;
         // Race guard: the user (or another client) may have already
         // resolved the permission while we were realpath-ing.
-        if (!sessions.pendingPermissions.has(event.requestId))
+        if (!tasks.pendingPermissions.has(event.requestId))
             return;
-        performAutoApprove(event, opt, sessions, store, bridge, sseManager, false);
+        performAutoApprove(event, opt, tasks, store, bridge, sseManager, false);
     }, (err) => {
         ailog.warn("unexpected error", { error: err.message });
     });
 }
-function handlePermissionRequest(event, sessions, store, bridge, sseManager, config) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handlePermissionRequest(event, tasks, store, bridge, sseManager, config) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         requestId: event.requestId,
         title: event.title,
         options: event.options,
     }, { from_ref: "agent" });
-    sessions.pendingPermissions.set(event.requestId, {
+    tasks.pendingPermissions.set(event.requestId, {
         requestId: event.requestId,
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         title: event.title,
         options: event.options.map((o) => ({
             optionId: o.optionId,
             label: o.label ?? o.name ?? o.optionId,
         })),
     });
-    sessions.syncPendingPermissions(event.sessionId);
-    const autopiloted = maybeAutoApprovePermission(event, sessions, store, bridge, sseManager);
+    tasks.syncPendingPermissions(event.taskId);
+    const autopiloted = maybeAutoApprovePermission(event, tasks, store, bridge, sseManager);
     if (autopiloted)
         return true;
     // Async attachment-read auto-approve runs after the request broadcasts.
-    maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManager, config);
+    maybeAutoApproveAttachmentRead(event, tasks, store, bridge, sseManager, config);
     return false;
 }
-function handlePromptDone(event, sessions, store) {
-    const cancelStatus = sessions.state.getState(event.sessionId).runtime.busy?.cancelStatus ?? null;
+function handlePromptDone(event, tasks, store, bridge) {
+    const cancelStatus = tasks.state.getState(event.taskId).runtime.busy?.cancelStatus ?? null;
     if (cancelStatus !== null) {
         clog.info("agent completed after request", {
-            sessionId: event.sessionId.slice(0, 8),
+            taskId: event.taskId.slice(0, 8),
             requestedStatus: cancelStatus,
             stopReason: event.stopReason,
         });
     }
     // The tail this turn buffered must always land, even when the turn has
     // already been superseded — it is the only copy of that text.
-    const isCurrent = sessions.isCurrentPrompt(event.sessionId, event.promptId);
+    const isCurrent = tasks.isCurrentPrompt(event.taskId, event.promptId);
+    const taskBeforeIdle = isCurrent ? store.getTask(event.taskId) : null;
+    // Only Agent-created delegated Tasks owe a lifecycle handoff. User-created
+    // Tasks may receive the same collaboration content but remain interactive.
+    const needsHandoffReminder = isCurrent &&
+        taskBeforeIdle?.source === "agent" &&
+        event.stopReason !== "cancelled" &&
+        taskBeforeIdle.workflow_status === "running";
     if (isCurrent) {
-        sessions.activePrompts.delete(event.sessionId);
-        sessions.syncBusy(event.sessionId);
+        tasks.activePrompts.delete(event.taskId);
+        tasks.syncBusy(event.taskId);
     }
     else {
         clog.info("completion from a superseded turn", {
-            sessionId: event.sessionId.slice(0, 8),
+            taskId: event.taskId.slice(0, 8),
             promptId: event.promptId,
             stopReason: event.stopReason,
         });
     }
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         stopReason: event.stopReason,
         // Replay must be able to make the same judgement the live path does.
         ...(event.promptId ? { promptId: event.promptId } : {}),
     }, { from_ref: "agent" });
+    if (isCurrent) {
+        if (taskBeforeIdle?.workflow_status === "running") {
+            store.updateTaskWorkflowStatus(event.taskId, "idle");
+        }
+        // Defer past the synchronous prompt_done broadcast below: a busy patch
+        // minted by the drain must never race ahead of the finished turn's own
+        // terminator, or clients drop the terminator as a superseded turn and
+        // strand its pending tool/permission UI.
+        void Promise.resolve()
+            .then(async () => {
+            const drained = await tasks.drainCollaborationDeliveries(bridge, event.taskId);
+            if (!drained && needsHandoffReminder) {
+                await tasks.promptHandoffReminder(bridge, event.taskId);
+            }
+        })
+            .catch((error) => {
+            clog.warn("handoff recovery failed", {
+                taskId: event.taskId.slice(0, 8),
+                error,
+            });
+        });
+    }
 }
-function handleError(event, sessions) {
-    if (event.sessionId) {
+function handleError(event, tasks, store, bridge) {
+    if (event.taskId) {
+        const taskId = event.taskId;
         // Same attribution as a completion: a superseded turn failing late must
         // not end the turn that replaced it. The buffered tail still flushes.
-        if (sessions.isCurrentPrompt(event.sessionId, event.promptId)) {
-            sessions.activePrompts.delete(event.sessionId);
-            sessions.syncBusy(event.sessionId);
+        const isCurrent = tasks.isCurrentPrompt(event.taskId, event.promptId);
+        const taskBeforeIdle = isCurrent ? store.getTask(event.taskId) : null;
+        const needsHandoffReminder = isCurrent &&
+            taskBeforeIdle?.source === "agent" &&
+            taskBeforeIdle.workflow_status === "running";
+        if (isCurrent) {
+            tasks.activePrompts.delete(event.taskId);
+            tasks.syncBusy(event.taskId);
         }
         else {
             clog.info("failure from a superseded turn", {
-                sessionId: event.sessionId.slice(0, 8),
+                taskId: event.taskId.slice(0, 8),
                 promptId: event.promptId,
                 message: event.message,
             });
         }
-        sessions.flushBuffers(event.sessionId);
-        sessions.state.patch(event.sessionId, {
+        tasks.flushBuffers(event.taskId);
+        tasks.state.patch(event.taskId, {
             runtime: { streaming: { assistant: false, thinking: false } },
         });
+        store.saveEvent(event.taskId, event.type, {
+            message: event.message,
+            ...(event.promptId ? { promptId: event.promptId } : {}),
+        }, { from_ref: "agent" });
+        if (isCurrent) {
+            if (taskBeforeIdle?.workflow_status === "running") {
+                store.updateTaskWorkflowStatus(event.taskId, "idle");
+            }
+            void Promise.resolve()
+                .then(async () => {
+                const drained = await tasks.drainCollaborationDeliveries(bridge, taskId);
+                if (!drained && needsHandoffReminder) {
+                    await tasks.promptHandoffReminder(bridge, taskId);
+                }
+            })
+                .catch((recoveryError) => {
+                clog.warn("handoff recovery failed after agent error", {
+                    taskId: taskId.slice(0, 8),
+                    error: recoveryError,
+                });
+            });
+        }
     }
 }
-function dispatchAgentEvent(event, sessions, store, bridge, config, sseManager) {
+function dispatchAgentEvent(event, tasks, store, bridge, config, sseManager) {
     // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- only handles events with side effects
     switch (event.type) {
         case "connected":
-            handleConnected(event, sessions, config);
+            handleConnected(event, tasks, config);
             return false;
-        case "session_created":
+        case "task_created":
         case "config_option_update":
-            handleConfigLikeEvent(event, sessions);
+            handleConfigLikeEvent(event, tasks);
             return false;
         case "message_chunk":
-            handleMessageChunk(event, sessions);
+            handleMessageChunk(event, tasks);
             return false;
         case "thought_chunk":
-            handleThoughtChunk(event, sessions);
+            handleThoughtChunk(event, tasks);
             return false;
         case "tool_call":
-            handleToolCall(event, sessions, store);
+            handleToolCall(event, tasks, store);
             return false;
         case "tool_call_update":
-            store.saveEvent(event.sessionId, event.type, { id: event.id, status: event.status, content: event.content }, { from_ref: "agent" });
+            store.saveEvent(event.taskId, event.type, {
+                id: event.id,
+                status: event.status,
+                content: event.content,
+                title: event.title,
+                kind: event.kind,
+                rawInput: event.rawInput,
+                locations: event.locations,
+            }, { from_ref: "agent" });
             return false;
         case "plan":
-            handlePlan(event, sessions, store);
+            handlePlan(event, tasks, store);
             return false;
         case "permission_request":
-            return handlePermissionRequest(event, sessions, store, bridge, sseManager, config);
+            return handlePermissionRequest(event, tasks, store, bridge, sseManager, config);
         case "prompt_done":
-            handlePromptDone(event, sessions, store);
+            handlePromptDone(event, tasks, store, bridge);
             return false;
         case "error":
-            handleError(event, sessions);
+            handleError(event, tasks, store, bridge);
             return false;
     }
     return false;
 }
 function maybePushNotify(event, pushService) {
-    if (!("sessionId" in event) || !event.sessionId)
+    if (!("taskId" in event) || !event.taskId)
         return;
     const pushEvent = {
         type: event.type,
@@ -248,36 +324,41 @@ function maybePushNotify(event, pushService) {
         // bash_done has `code` not `exitCode`; command not stored in the event
         pushEvent.exitCode = event.code ?? undefined;
     }
-    pushService.sendForEvent(event.sessionId, pushEvent).catch((err) => {
+    pushService.sendForEvent(event.taskId, pushEvent).catch((err) => {
         plog.error("failed to send", { error: err });
     });
 }
-export function handleAgentEvent(event, sessions, store, bridge, config, sseManager, pushService, _clientRegistry) {
+export function handleAgentEvent(event, tasks, store, bridge, config, sseManager, pushService, _clientRegistry) {
+    if (event.type === "usage_update") {
+        handleUsageUpdate(event, tasks);
+        return;
+    }
     if (event.type === "available_commands_update") {
-        const snapshot = sessions.updateAgentCommands(event.sessionId, event.commands);
-        if (sessions.restoringSessions.has(event.sessionId))
+        const snapshot = tasks.updateAgentCommands(event.taskId, event.commands);
+        if (tasks.restoringTasks.has(event.taskId))
             return;
         sseManager.broadcast({ ...event, ...snapshot });
         return;
     }
     if (event.type === "agent_reloading" || event.type === "agent_disconnected") {
-        for (const sessionId of sessions.liveSessions) {
-            sessions.flushBuffers(sessionId);
+        for (const taskId of tasks.liveTasks) {
+            tasks.flushBuffers(taskId);
         }
-        sessions.state.clearStreaming();
-        sessions.state.clearPlans();
-        for (const snapshot of sessions.clearAgentCommands()) {
+        tasks.state.clearStreaming();
+        tasks.state.clearPlans();
+        tasks.state.clearContextUsage();
+        for (const snapshot of tasks.clearAgentCommands()) {
             sseManager.broadcast({
                 type: "available_commands_update",
                 ...snapshot,
             });
         }
     }
-    if ("sessionId" in event &&
-        event.sessionId &&
-        sessions.restoringSessions.has(event.sessionId))
+    if ("taskId" in event &&
+        event.taskId &&
+        tasks.restoringTasks.has(event.taskId))
         return;
-    const suppress = dispatchAgentEvent(event, sessions, store, bridge, config, sseManager);
+    const suppress = dispatchAgentEvent(event, tasks, store, bridge, config, sseManager);
     if (suppress)
         return;
     sseManager.broadcast(event);

package/lib/files/limits.js

@@ -0,0 +1,15 @@
+/**
+ * File viewer size limits.
+ *
+ * Kept as plain exported constants for now so the routes have a single,
+ * testable knob; wiring these into `[limits]` config is a later milestone.
+ * Values stay in the same order of magnitude as attachment limits and keep
+ * rendered previews bounded. Files outside preview limits stream as downloads
+ * instead of being buffered in server or browser memory.
+ */
+/** Directory listings cap — beyond this the response is truncated + flagged. */
+export const MAX_LIST_ITEMS = 2000;
+/** Text/Markdown/code preview + highlight cap; larger files download. */
+export const MAX_TEXT_PREVIEW_BYTES = 1024 * 1024; // 1 MiB
+/** Image render cap — larger images stream as downloads. */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // 20 MB

package/lib/files/paths.js

@@ -0,0 +1,155 @@
+/**
+ * Path resolution and directory listing helpers for the file viewer.
+ *
+ * Contract (confirmed design): the viewer accepts *absolute* paths or `~`
+ * prefixes only — relative paths are rejected outright so there is no base
+ * ambiguity to exploit. `~` expands to HOME, then `realpath` canonicalizes
+ * symlinks and `..` segments once; every path on the system is legal by
+ * design (single-owner personal tool), so there is deliberately no escape
+ * rejection logic — the guards here prevent blocking on special files,
+ * unbounded directory scans, and whole-file buffering.
+ */
+import { constants } from "node:fs";
+import { open, opendir, realpath, stat, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, basename } from "node:path";
+import { expandHomePath } from "../home-path.js";
+import { MAX_LIST_ITEMS } from "./limits.js";
+/** HTTP status-backed error; routes map it to a JSON error response. */
+export class FilePathError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Expand a user-supplied path string into an absolute path.
+ * Accepts `/absolute/path` and `~/...` / `~`. Everything else (including
+ * `~user` and bare relative paths) is rejected with 400.
+ */
+export function expandPath(raw, home = homedir()) {
+    if (raw.length === 0)
+        throw new FilePathError(400, "Missing path");
+    if (raw.includes("\0"))
+        throw new FilePathError(400, "Invalid path");
+    const expanded = expandHomePath(raw, home);
+    if (raw.startsWith("~") && expanded === raw) {
+        throw new FilePathError(400, "Unsupported ~user expansion");
+    }
+    if (!isAbsolute(expanded)) {
+        throw new FilePathError(400, "Path must be absolute or start with ~");
+    }
+    return expanded;
+}
+/** realpath canonicalization; missing paths map to 404. */
+export async function canonicalize(target) {
+    try {
+        return await realpath(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new FilePathError(404, "Path does not exist");
+        }
+        throw err;
+    }
+}
+/** stat a canonical path; non-regular files (fifo/socket/device) → 400. */
+export async function statMeta(path) {
+    const s = await stat(path);
+    let kind;
+    if (s.isFile())
+        kind = "file";
+    else if (s.isDirectory())
+        kind = "dir";
+    else
+        throw new FilePathError(400, "Not a regular file or directory");
+    return {
+        path,
+        name: basename(path),
+        kind,
+        size: s.size,
+        mtime: s.mtimeMs,
+    };
+}
+/**
+ * List one directory: scan at most MAX_LIST_ITEMS plus one sentinel raw entry,
+ * omit dotfiles/special nodes, then sort the bounded result dirs-first and
+ * lexicographically. Entries that vanish mid-list are skipped.
+ */
+export async function listDirectory(target) {
+    const dir = await opendir(target);
+    const entries = [];
+    let scanned = 0;
+    let truncated = false;
+    // Dir's async iterator closes the descriptor both at EOF and on break.
+    for await (const entry of dir) {
+        scanned++;
+        // Read one sentinel beyond the cap so `truncated` is authoritative,
+        // but never materialize/sort an unbounded directory.
+        if (scanned > MAX_LIST_ITEMS) {
+            truncated = true;
+            break;
+        }
+        if (entry.name.startsWith("."))
+            continue;
+        try {
+            const s = await stat(join(target, entry.name));
+            // Only expose targets the viewer can actually open. Symlinks to
+            // regular files/dirs pass because stat follows them; fifos, sockets,
+            // and devices are omitted rather than mislabelled as files.
+            if (!s.isDirectory() && !s.isFile())
+                continue;
+            entries.push({
+                name: entry.name,
+                kind: s.isDirectory() ? "dir" : "file",
+                size: s.isFile() ? s.size : null,
+                mtime: s.mtimeMs,
+            });
+        }
+        catch {
+            // Raced deletion — skip rather than fail the whole listing.
+        }
+    }
+    entries.sort(compareEntries);
+    return { entries, truncated };
+}
+function compareEntries(a, b) {
+    if (a.kind !== b.kind)
+        return a.kind === "dir" ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/** Read up to `n` bytes from the head of a regular file (mime sniffing). */
+export async function readHead(file, n = 4096) {
+    const h = await open(file, "r");
+    try {
+        const st = await h.stat();
+        const len = Math.min(st.size, n);
+        const buf = Buffer.alloc(len);
+        if (len > 0)
+            await h.read(buf, 0, len, 0);
+        return buf;
+    }
+    finally {
+        await h.close();
+    }
+}
+/**
+ * Open without following a final symlink and without blocking on a FIFO.
+ * Windows lacks equivalent POSIX flags; fstat below remains authoritative.
+ */
+export function openForStreaming(file) {
+    const safeFlags = process.platform === "win32"
+        ? constants.O_RDONLY
+        : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    return open(file, safeFlags);
+}
+/** Read mime-sniff bytes from an already validated descriptor. */
+export async function readHandleHead(handle, size, n = 4096) {
+    const len = Math.min(size, n);
+    const buf = Buffer.alloc(len);
+    if (len === 0)
+        return buf;
+    const { bytesRead } = await handle.read(buf, 0, len, 0);
+    return buf.subarray(0, bytesRead);
+}