@tea-agent/loop-agent 0.40.0-next.11 → 0.40.0-next.13

package/dist/worker/console/chat/pi-runtime.js

@@ -36,10 +36,13 @@ import { OPERATOR_CHAT_ALLOWED_TOOLS, authorizeOperatorChatTool, assertNoWriteTo
 import { createOperatorChatResourceLoader, } from "./resource-loader.js";
 import { applySkillAutoInvocationPreferences, isAutoInvocationEnabled, loadResourcePreferences, skillResourceId, } from "./resource-preferences-store.js";
 import { buildModelCallableToolSchemas } from "./tool-adapter.js";
+import { applyProcessCompactionOverride, createCompactionController, createContextPressureExtension, createSiftBridgeState, housekeepSiftStash, isConsoleSiftEnabled, parseCompactionPolicy, parseSiftBridgeConfig, projectPromptPressure, deriveEffectiveWindow, projectSafeTelemetry, emptyContextPressureCounters, } from "../../../shared/pi-context-pressure/index.js";
+import { incrementCounter as incrementPressureCounter } from "../../../shared/pi-context-pressure/telemetry.js";
 import { resolveDefaultChatModel, resolveLowChatModel, } from "./model-resolver.js";
 import { filterActiveInterviewTools } from "../interview/tools.js";
 import { RUNTIME_CONTEXT_TEXT_MAX, redactRuntimeText, } from "./runtime-context.js";
 import { buildTodoContinuationContext, } from "./todos.js";
+import { buildGoalContinuationContext, } from "./goals.js";
 /**
  * Base system prompt fragment every General Operator Chat session receives.
  *
@@ -64,9 +67,9 @@ export const OPERATOR_CHAT_SYSTEM_PROMPT_BASE = [
     "You are General Operator Chat.",
     "Use operator tools first (dagReport, dagRerunPlan, dagRerun). Pi read/write/edit/bash/grep/find/ls are available; obey repository AGENTS.md. apply_patch, full-tools, shell and coding-chat are denied. Prefer safe-read/safe-grep for probes.",
     "No harness and asked to init: `loop-agent init instructions --repo-root .`, then `loop-agent init --repo-root . --profile full --merge`; verify with doctor, inspect and docs audit. Updates: `loop-agent init upgrade --repo-root . --json` until stable; `loop-agent init check-update` is read-only.",
-    "Long DAGs: prepareDagExecution → runDag → operationId. Never foreground-Bash task advance, tail/head pipes or nohup/Start-Process/start; do not end on accepted/queued/running or an operationId — NOT completion. Supervise operationGet/status/dagReport/dagDoctor/operationWait with 60s → 90s → 120s → 180s backoff; reset to 60s on state change; 30-60s re-checks when stall suspected. Every operationWait continuation MUST use afterSeq=previous nextSeq (prefer recommendedNextCall); never reuse an older cursor. Heartbeats are not meaningful progress.",
-    "On failure consume terminal runSummary first. If progress exists, wait; else dagReport then dagRerunPlan(fromNode=primaryFailure.nodeId); eligible → dagRerun (node rerun only: reruns the failed subgraph, keeps prior successes). If plan ineligible (unsafe-shell subgraph, binding/workspace drift): Worker Failed → workerTaskRetry; standalone → standaloneTaskRerun after contract adopt (regenerates the whole task, not node continue). Do not call dagResume. A run-failed task without an open gate is terminal: do not re-advance a run-failed task. Before run start, two identical lifecycleState/blocker/revision/DAG-hash observations mean no progress: stop and report after one bounded probe; never loop identical bash/read/grep. Auto-approve only bounded writeSet inside allowedPaths, outside forbiddenPaths, with structured verification.",
-    "Iterate toward the goal in bounded rounds: first summarize the previous round's error in one line (wrong fix, wrong node, or environment), fix its root cause — not the symptom — then rerun the failed node with a fresh plan. Never resubmit an unchanged fix; after two rounds failing the same way, stop and report evidence and remaining routes.",
+    "Long DAGs: prepareDagExecution → runDag → operationId. Never foreground-Bash task advance, tail/head pipes or nohup/Start-Process/start; do not end on accepted/queued/running or an operationId — NOT completion. Supervise operationGet/status/dagReport/dagDoctor/operationWait with 60s → 90s → 120s → 180s backoff; reset to 60s on state change; 30-60s re-checks when stall suspected. Every operationWait continuation MUST use afterSeq=previous nextSeq (recommendedNextCall); never reuse older cursors. Heartbeats: not meaningful progress. Run id 20260829-slug ≠ task id 2026-08-29-slug.",
+    "On failure consume terminal runSummary first. If progress exists, wait; else dagReport then dagRerunPlan(fromNode=primaryFailure.nodeId); eligible → dagRerun (node rerun only: reruns the failed subgraph, keeps prior successes). If plan ineligible (unsafe-shell subgraph, binding/workspace drift): Worker Failed → workerTaskRetry; standalone → standaloneTaskRerun after contract adopt (regenerates the whole task, not node continue). Do not call dagResume. Run-failed task without open gate is terminal: do not re-advance a run-failed task. Before run start, two identical lifecycleState/blocker/revision/DAG-hash observations mean no progress: stop and report after one bounded probe; never loop identical bash/read/grep. Auto-approve only bounded writeSet inside allowedPaths, outside forbiddenPaths, with structured verification.",
+    "Iterate toward the goal in bounded rounds: first summarize the previous round's error in one line, fix its root cause — not the symptom — then rerun the failed node with a fresh plan. Never resubmit an unchanged fix; after two rounds failing the same way, stop and report evidence and remaining routes.",
     "Continue until success, user stop, or no safe recovery remains; then stop and report failure/evidence. Never create a new task for a transient failure or replace repair-pi with direct edits.",
 ].join("\n");
 /** Compose the inspectable system prompt actually injected into Operator Chat. */
@@ -257,6 +260,43 @@ export function createTodoCompactionContextExtension(options) {
         },
     };
 }
+/** Goal survives compaction and Turn boundaries; unlike Todo it is not reset
+ * at turn_start. The extension only injects after a successful compaction so
+ * ordinary contexts still rely on the model-callable get_goal source. */
+export function createGoalCompactionContextExtension(options) {
+    return {
+        name: "operator-chat-goal-compaction-context",
+        hidden: true,
+        factory: (api) => {
+            let compacted = false;
+            api.on("session_compact", () => {
+                compacted = true;
+            });
+            api.on("context", (rawEvent) => {
+                if (!compacted)
+                    return undefined;
+                const goal = options.registry.get(options.sessionId);
+                const context = buildGoalContinuationContext(goal);
+                if (!context)
+                    return undefined;
+                const messages = Array.isArray(rawEvent.messages) ? rawEvent.messages : [];
+                return {
+                    messages: [
+                        ...messages,
+                        {
+                            role: "custom",
+                            customType: "operator-chat-goal-context",
+                            content: context,
+                            display: false,
+                            details: { goal },
+                            timestamp: Date.now(),
+                        },
+                    ],
+                };
+            });
+        },
+    };
+}
 /**
  * Build Pi custom ToolDefinition objects for every whitelisted operator action.
  * Each tool's execute() routes into the operator action dispatcher (Gate 3).
@@ -406,6 +446,80 @@ async function buildTodoWriteTool(options) {
         },
     });
 }
+const GET_GOAL_DESCRIPTION = "Read the current session's durable cross-turn Goal, including revision, status, round limit, and whether this Console process is authorized to continue it.";
+const CREATE_GOAL_DESCRIPTION = "Create a durable cross-turn Goal only when the user explicitly asks to start or create a Goal. Never silently upgrade an ordinary request. A session may have only one unfinished Goal.";
+const UPDATE_GOAL_DESCRIPTION = "Finish or block the current durable Goal using its exact goalId and revision. Set complete only when the objective is genuinely achieved and no required work remains. Set blocked only when safe progress cannot continue; include the blocker.";
+async function buildGoalTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const textResult = (value) => ({
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        details: value,
+    });
+    return [
+        defineTool({
+            name: "get_goal",
+            label: "Get goal",
+            description: GET_GOAL_DESCRIPTION,
+            promptSnippet: GET_GOAL_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return textResult({ goal: options.registry.get(options.sessionId) });
+            },
+        }),
+        defineTool({
+            name: "create_goal",
+            label: "Create goal",
+            description: CREATE_GOAL_DESCRIPTION,
+            promptSnippet: CREATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                objective: Type.String({
+                    description: "Concrete final objective and completion standard explicitly requested by the user.",
+                }),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                if (!options.registry.consumeModelCreateGrant(options.sessionId)) {
+                    return textResult({
+                        ok: false,
+                        code: "GOAL_EXPLICIT_REQUEST_REQUIRED",
+                        message: "create_goal requires an explicit user request to create or start a Goal",
+                    });
+                }
+                return textResult(options.registry.create({
+                    sessionId: options.sessionId,
+                    objective: params.objective,
+                }));
+            },
+        }),
+        defineTool({
+            name: "update_goal",
+            label: "Update goal",
+            description: UPDATE_GOAL_DESCRIPTION,
+            promptSnippet: UPDATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                goalId: Type.String(),
+                revision: Type.Number({ minimum: 1 }),
+                status: Type.Union([
+                    Type.Literal("complete"),
+                    Type.Literal("blocked"),
+                ]),
+                blocker: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return textResult(options.registry.update({
+                    sessionId: options.sessionId,
+                    goalId: params.goalId,
+                    expectedRevision: params.revision,
+                    phase: params.status,
+                    blocker: params.blocker,
+                    arm: false,
+                }));
+            },
+        }),
+    ];
+}
 /**
  * Build the safe explore custom tools (roadmap M0-A / G16): safe-read,
  * safe-grep, gitStatus, gitDiff. These replace the bare SDK bash/read/grep so
@@ -845,6 +959,9 @@ export class ConsolePiRuntime {
     sessionModels = new Map();
     /** SessionIds disposed while materialization was still in flight. */
     disposedSessions = new Set();
+    compactionControllers = new Map();
+    siftStates = new Map();
+    /** Session-less tool definition caches (no AgentSession state). */
     /** Session-less tool definition caches (no AgentSession state). */
     operatorCustomToolsPromise;
     exploreCustomToolsPromise;
@@ -892,14 +1009,25 @@ export class ConsolePiRuntime {
                 registry: this.options.todoRegistry,
             })
             : undefined;
+        const pressureExtension = sessionId
+            ? this.createContextPressureInlineExtension(sessionId)
+            : undefined;
+        const goalContextExtension = sessionId && this.options.goalRegistry
+            ? createGoalCompactionContextExtension({
+                sessionId,
+                registry: this.options.goalRegistry,
+            })
+            : undefined;
+        const extraFactories = [
+            todoContextExtension,
+            goalContextExtension,
+            pressureExtension,
+        ].filter((item) => Boolean(item));
         return {
             ...base,
-            ...(todoContextExtension
+            ...(extraFactories.length > 0
                 ? {
-                    extensionFactories: [
-                        ...inheritedFactories,
-                        todoContextExtension,
-                    ],
+                    extensionFactories: [...inheritedFactories, ...extraFactories],
                 }
                 : {}),
             skillsOverride: (current) => {
@@ -924,6 +1052,126 @@ export class ConsolePiRuntime {
         this.cachedSkillPrefs = prefs;
         return prefs;
     }
+    getCompactionController(sessionId) {
+        let controller = this.compactionControllers.get(sessionId);
+        if (!controller) {
+            controller = createCompactionController();
+            this.compactionControllers.set(sessionId, controller);
+        }
+        if (this.options.todoRegistry) {
+            controller.todos = this.options.todoRegistry.get(sessionId);
+        }
+        return controller;
+    }
+    createContextPressureInlineExtension(sessionId) {
+        const policy = parseCompactionPolicy();
+        const siftEnabled = isConsoleSiftEnabled();
+        let sift;
+        if (siftEnabled.enabled) {
+            sift = this.siftStates.get(sessionId);
+            if (!sift) {
+                const config = parseSiftBridgeConfig({
+                    sessionId,
+                    defaultStashRoot: path.join(this.options.sessionDir, "sift-stash"),
+                });
+                sift = createSiftBridgeState(config);
+                sift.counters = this.getCompactionController(sessionId).counters;
+                this.siftStates.set(sessionId, sift);
+                const housekeep = housekeepSiftStash({
+                    root: path.dirname(config.stashDir),
+                    activeSessionId: sessionId,
+                    retentionDays: config.retentionDays,
+                });
+                if (housekeep.failed)
+                    sift.diagnostics.add("housekeep-failed");
+            }
+        }
+        return createContextPressureExtension({
+            name: "operator-chat-context-pressure",
+            policy,
+            controller: this.getCompactionController(sessionId),
+            sift,
+        });
+    }
+    applySessionCompactionOverride(sessionId, services, session) {
+        const manager = services?.settingsManager;
+        const window = session?.getSessionStats?.()?.contextUsage?.contextWindow;
+        applyProcessCompactionOverride(manager, {
+            policy: parseCompactionPolicy(),
+            ...(typeof window === "number" ? { contextWindow: window } : {}),
+        });
+        void sessionId;
+    }
+    async runPrePromptCompaction(sessionId, session, promptText, imageCount, onEvent) {
+        const policy = parseCompactionPolicy();
+        if (policy.mode === "off")
+            return;
+        const controller = this.getCompactionController(sessionId);
+        const stats = session.getSessionStats?.();
+        const window = stats?.contextUsage?.contextWindow;
+        const tokens = stats?.contextUsage?.tokens;
+        if (typeof window === "number" && window > 0) {
+            this.applySessionCompactionOverride(sessionId, this.serviceScopes.get(sessionId) ?? {}, session);
+        }
+        const projection = projectPromptPressure({
+            currentContextTokens: tokens,
+            promptText,
+            imageCount,
+        });
+        if (projection.usageUnavailable) {
+            incrementPressureCounter(controller.counters, "usage-unavailable");
+            return;
+        }
+        const effective = typeof window === "number" && window > 0
+            ? deriveEffectiveWindow(window, policy)
+            : undefined;
+        if (!effective || projection.projected < effective.triggerTokens)
+            return;
+        if (typeof session.compact !== "function")
+            return;
+        const compactionId = newCompactionId(sessionId);
+        onEvent({
+            type: "compaction_start",
+            sessionId,
+            compactionId,
+            reason: "threshold",
+        });
+        controller.proactiveCompaction = true;
+        try {
+            incrementPressureCounter(controller.counters, "pre-prompt-threshold");
+            const result = await session.compact();
+            const snapshot = projectCompactSnapshot(result ?? {});
+            onEvent({
+                type: "compaction_end",
+                sessionId,
+                compactionId,
+                reason: "threshold",
+                status: "completed",
+                willRetry: false,
+                summary: snapshot.summary,
+                ...(snapshot.firstKeptEntryId
+                    ? { firstKeptEntryId: snapshot.firstKeptEntryId }
+                    : {}),
+                ...(snapshot.tokensBefore === undefined
+                    ? {}
+                    : { tokensBefore: snapshot.tokensBefore }),
+            });
+        }
+        catch {
+            incrementPressureCounter(controller.counters, "l0-compact-failed");
+            onEvent({
+                type: "compaction_end",
+                sessionId,
+                compactionId,
+                reason: "threshold",
+                status: "failed",
+                willRetry: false,
+            });
+        }
+        finally {
+            controller.proactiveCompaction = false;
+        }
+    }
     /**
      * Resolve a skill in the current session inventory by server-issued resourceId.
      * Returns undefined when the id is unknown (caller maps to PI_SKILL_NOT_FOUND).
@@ -1156,6 +1404,7 @@ export class ConsolePiRuntime {
             resourceLoader: services.resourceLoader,
             settingsManager: services.settingsManager,
         });
+        this.applySessionCompactionOverride(sessionId, services, session);
         this.revisions.set(sessionId, 1);
         if (!this.thinkingSelections.has(sessionId)) {
             this.thinkingSelections.set(sessionId, "auto");
@@ -1191,11 +1440,15 @@ export class ConsolePiRuntime {
         const todoTool = this.options.todoRegistry
             ? await buildTodoWriteTool({ sessionId, registry: this.options.todoRegistry })
             : undefined;
+        const goalTools = this.options.goalRegistry
+            ? await buildGoalTools({ sessionId, registry: this.options.goalRegistry })
+            : [];
         return [
             ...operatorCustomTools,
             ...exploreCustomTools,
             ...(questionTool ? [questionTool] : []),
             ...(todoTool ? [todoTool] : []),
+            ...goalTools,
         ];
     }
     loadOperatorCustomTools() {
@@ -1470,6 +1723,9 @@ export class ConsolePiRuntime {
             // the latest resource-preferences.json written by PATCH.
             await this.refreshSkillPrefsCache().catch(() => undefined);
             await session.reload();
+            const services = this.serviceScopes.get(sessionId);
+            if (services)
+                this.applySessionCompactionOverride(sessionId, services, session);
         }
         catch (error) {
             return {
@@ -1482,6 +1738,9 @@ export class ConsolePiRuntime {
             this.reloadInFlight.delete(sessionId);
         }
         this.bumpRevision(sessionId);
+        // Reload replaces the effective resource/session context. Persisted Goal
+        // remains visible, but continuation authorization must be renewed by user.
+        this.options.goalRegistry?.disarm(sessionId);
         return { ok: true, revision: this.revisions.get(sessionId) ?? 0 };
     }
     /**
@@ -1927,6 +2186,9 @@ export class ConsolePiRuntime {
         if (this.sessions.has(sessionId)) {
             return { ok: true, handle: await this.snapshotActive(sessionId) };
         }
+        // A newly materialized Pi session must never inherit process-local Goal
+        // activation from an earlier disposed runtime instance.
+        this.options.goalRegistry?.disarm(sessionId);
         if (!init.sessionFile) {
             return {
                 ok: false,
@@ -2076,6 +2338,7 @@ export class ConsolePiRuntime {
         });
         await bindSessionExtensions(session);
         pinOperatorChatTools(session);
+        this.applySessionCompactionOverride(init.sessionId, services, session);
         return {
             session,
             modelRuntime,
@@ -2117,6 +2380,12 @@ export class ConsolePiRuntime {
                 session?.hasPendingBashMessages === true,
         };
     }
+    /** Low-cardinality context-pressure counters; never includes payload text. */
+    getContextPressureTelemetry(sessionId) {
+        const counters = this.compactionControllers.get(sessionId)?.counters ??
+            this.siftStates.get(sessionId)?.counters;
+        return projectSafeTelemetry(counters ?? emptyContextPressureCounters());
+    }
     /**
      * Send a prompt and stream events. Gate 3: each tool invocation is
      * re-authorized by authorizeOperatorChatTool before the dispatcher runs it
@@ -2159,6 +2428,9 @@ export class ConsolePiRuntime {
             if (options?.turnId && this.options.todoRegistry) {
                 this.options.todoRegistry.startTurn(sessionId, options.turnId);
             }
+            if (this.options.goalRegistry) {
+                this.options.goalRegistry.startTurn(sessionId, text);
+            }
             // AC-FIX-002: if Stop already fired before readiness, never start model work.
             if (options?.signal?.aborted) {
                 return;
@@ -2212,6 +2484,7 @@ export class ConsolePiRuntime {
                 }
             };
             emitContextUsage();
+            await this.runPrePromptCompaction(sessionId, session, text, options?.images?.length ?? 0, onEvent);
             let stepStartedAt;
             let firstTokenAt;
             let pendingProviderError;
@@ -2461,13 +2734,17 @@ export class ConsolePiRuntime {
             throw new Error("CHAT_TURN_ACTIVE");
         if (typeof session.compact !== "function")
             throw new Error("COMPACTION_UNSUPPORTED");
+        incrementPressureCounter(this.getCompactionController(sessionId).counters, "manual");
         const result = await session.compact(customInstructions);
         return projectCompactSnapshot(result ?? {});
     }
     dispose(sessionId) {
         // Mark disposed first so a late materialization never registers ready.
         this.disposedSessions.add(sessionId);
+        this.options.goalRegistry?.disarm(sessionId);
         this.sessionInit.delete(sessionId);
+        this.compactionControllers.delete(sessionId);
+        this.siftStates.delete(sessionId);
         const session = this.sessions.get(sessionId);
         if (session) {
             try {

package/dist/worker/console/chat/provider-error.js

@@ -1,3 +1,4 @@
+import { isContextOverflow } from "../../../shared/pi-context-pressure/overflow.js";
 const MAX_RAW_CHARS = 8_000;
 const MAX_MESSAGE_CHARS = 1_000;
 function asRecord(value) {
@@ -52,7 +53,7 @@ function classify(input) {
         status === 403 ||
         /认证|鉴权|unauthori[sz]ed|forbidden|authentication|invalid api[-_ ]?key/.test(haystack))
         return "authentication";
-    if (/请求上下文过大|上下文.{0,12}(?:过大|太大|过长|超限)|context_length_exceeded|maximum context|context.{0,24}(?:length|window|limit|large|long)|too many tokens/.test(haystack))
+    if (isContextOverflow(`${input.message}\n${input.raw}`))
         return "context-overflow";
     if (status === 429 ||
         /rate.?limit|too many requests|请求.{0,8}(?:频繁|过多)|限流/.test(haystack))

package/dist/worker/console/chat/repo-browser.js

@@ -4,8 +4,12 @@ import { lstat, open, readdir } from "node:fs/promises";
 import path from "node:path";
 import { guardReadPath, isSensitivePath, scrubSecrets, } from "./explore-tools.js";
 const TREE_LIMIT = 500;
-const READ_LIMIT = 256 * 1024;
-const RESPONSE_LIMIT = 128 * 1024;
+/** DSH-style bounded source read: large text files return this leading slice
+ * instead of being rejected solely because the complete file is larger. */
+export const TEXT_PREVIEW_LIMIT = 512 * 1024;
+/** Full-file ceiling for the sandboxed HTML preview route and its assets. */
+export const HTML_PREVIEW_ASSET_LIMIT = 20 * 1024 * 1024;
+export const REPO_HTML_PREVIEW_ROUTE_PREFIX = "/api/operator/v1/chat/repo/html/";
 const SKIP_DIRS = new Set([
     ".git",
     ".harness",
@@ -32,6 +36,45 @@ export class RepoBrowserError extends Error {
 function guardedCode(code) {
     return code === "PATH_OUTSIDE_REPO" ? "OUT_OF_REPO" : code;
 }
+/** Match the path-encoded HTML preview route. Keeping workspace + file path in
+ * the URL path lets browser-relative CSS/image references retain their scope. */
+export function matchRepoHtmlPreviewRoute(pathname) {
+    if (!pathname.startsWith(REPO_HTML_PREVIEW_ROUTE_PREFIX))
+        return null;
+    const rest = pathname.slice(REPO_HTML_PREVIEW_ROUTE_PREFIX.length);
+    const [workspaceId = "", ...pathSegments] = rest.split("/");
+    return { workspaceId, rawPath: pathSegments.join("/") };
+}
+export function repoHtmlAssetContentType(rawPath) {
+    const extension = path.extname(rawPath).toLowerCase();
+    const types = {
+        ".html": "text/html; charset=utf-8",
+        ".htm": "text/html; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".js": "text/javascript; charset=utf-8",
+        ".mjs": "text/javascript; charset=utf-8",
+        ".json": "application/json; charset=utf-8",
+        ".txt": "text/plain; charset=utf-8",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".avif": "image/avif",
+        ".bmp": "image/bmp",
+        ".ico": "image/x-icon",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf",
+        ".otf": "font/otf",
+        ".mp3": "audio/mpeg",
+        ".wav": "audio/wav",
+        ".mp4": "video/mp4",
+        ".webm": "video/webm",
+    };
+    return types[extension] ?? "application/octet-stream";
+}
 export async function listRepoDirectory(repoRoot, rawPath) {
     const root = rawPath === "";
     const guard = await guardReadPath(repoRoot, root ? "." : rawPath);
@@ -92,8 +135,6 @@ export async function readRepoPreview(repoRoot, rawPath) {
             const info = await handle.stat();
             if (!info.isFile())
                 throw new RepoBrowserError(400, "NOT_A_FILE", "path is not a regular file");
-            if (info.size > READ_LIMIT)
-                throw new RepoBrowserError(413, "TOO_LARGE", `file exceeds ${READ_LIMIT} byte preview limit`);
             const rechecked = await guardReadPath(repoRoot, rawPath);
             if (!rechecked.ok)
                 throw new RepoBrowserError(403, guardedCode(rechecked.code), "file path changed while it was being opened");
@@ -103,9 +144,10 @@ export async function readRepoPreview(repoRoot, rawPath) {
                 current.ino !== info.ino)
                 throw new RepoBrowserError(403, "OUT_OF_REPO", "file identity changed while it was being opened");
             size = info.size;
-            bytes = Buffer.alloc(size);
-            const bytesRead = size
-                ? (await handle.read(bytes, 0, size, 0)).bytesRead
+            const readSize = Math.min(size, TEXT_PREVIEW_LIMIT);
+            bytes = Buffer.alloc(readSize);
+            const bytesRead = readSize
+                ? (await handle.read(bytes, 0, readSize, 0)).bytesRead
                 : 0;
             bytes = bytes.subarray(0, bytesRead);
         }
@@ -114,17 +156,14 @@ export async function readRepoPreview(repoRoot, rawPath) {
         }
         if (bytes.includes(0))
             throw new RepoBrowserError(415, "BINARY_UNSUPPORTED", "binary files cannot be previewed");
-        let end = Math.min(bytes.length, RESPONSE_LIMIT);
-        while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80)
-            end -= 1;
-        const content = scrubSecrets(bytes.subarray(0, end).toString("utf8")).scrubbed;
+        const content = scrubSecrets(bytes.toString("utf8")).scrubbed;
         return {
             path: guard.repoRelative,
             kind: "text",
             content,
             language: path.extname(guard.repoRelative).slice(1).toLowerCase() || "text",
             bytes: size,
-            truncated: bytes.length > RESPONSE_LIMIT,
+            truncated: size > bytes.length,
             sha256: createHash("sha256").update(bytes).digest("hex"),
         };
     }
@@ -138,3 +177,46 @@ export async function readRepoPreview(repoRoot, rawPath) {
         throw error;
     }
 }
+/** Read one complete file for the sandboxed HTML iframe. Unlike source reads,
+ * this route needs complete HTML/CSS/image bytes so documents and relative
+ * assets render correctly; the separate 20 MiB cap keeps memory bounded. */
+export async function readRepoHtmlAsset(repoRoot, rawPath) {
+    const guard = await guardReadPath(repoRoot, rawPath);
+    if (!guard.ok)
+        throw new RepoBrowserError(403, guardedCode(guard.code), guard.message);
+    try {
+        const handle = await open(guard.abs, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile())
+                throw new RepoBrowserError(400, "NOT_A_FILE", "path is not a regular file");
+            if (info.size > HTML_PREVIEW_ASSET_LIMIT)
+                throw new RepoBrowserError(413, "TOO_LARGE", `file exceeds ${HTML_PREVIEW_ASSET_LIMIT} byte HTML preview limit`);
+            const rechecked = await guardReadPath(repoRoot, rawPath);
+            if (!rechecked.ok)
+                throw new RepoBrowserError(403, guardedCode(rechecked.code), "file path changed while it was being opened");
+            const current = await lstat(rechecked.abs);
+            if (current.isSymbolicLink() ||
+                current.dev !== info.dev ||
+                current.ino !== info.ino)
+                throw new RepoBrowserError(403, "OUT_OF_REPO", "file identity changed while it was being opened");
+            return {
+                body: await handle.readFile(),
+                contentType: repoHtmlAssetContentType(guard.repoRelative),
+                bytes: info.size,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof RepoBrowserError)
+            throw error;
+        if (error.code === "ENOENT")
+            throw new RepoBrowserError(404, "NOT_FOUND", "file does not exist");
+        if (error.code === "ELOOP")
+            throw new RepoBrowserError(403, "OUT_OF_REPO", "symbolic links are not previewable");
+        throw error;
+    }
+}