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

package/dist/worker/console/chat/goals.js

@@ -0,0 +1,300 @@
+import { randomUUID } from "node:crypto";
+export const DEFAULT_GOAL_MAX_ROUNDS = 32;
+function cloneGoal(goal) {
+    return structuredClone(goal);
+}
+export function normalizeGoalObjective(value) {
+    if (typeof value !== "string")
+        throw new Error("objective must be a string");
+    const objective = value.replace(/\r\n/g, "\n").trim();
+    if (!objective)
+        throw new Error("objective must not be empty");
+    if (objective.length > 8_000)
+        throw new Error("objective exceeds 8000 characters");
+    return objective;
+}
+export function isExplicitGoalCreationRequest(text) {
+    const normalized = text.trim().toLowerCase();
+    return (/^\/goal(?:\s|$)/i.test(normalized) ||
+        /(创建|新建|启动|开启|设定|设置).{0,10}(持续目标|goal)/i.test(normalized) ||
+        /(create|start|set up|enable).{0,16}\bgoal\b/i.test(normalized));
+}
+export function parseGoalSnapshot(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const item = value;
+    if (item.schemaVersion !== 1 ||
+        typeof item.goalId !== "string" ||
+        !item.goalId ||
+        !Number.isSafeInteger(item.revision) ||
+        (item.revision ?? 0) < 1 ||
+        typeof item.objective !== "string" ||
+        !item.objective.trim() ||
+        !["active", "paused", "blocked", "complete"].includes(item.phase) ||
+        !Number.isSafeInteger(item.round) ||
+        (item.round ?? -1) < 0 ||
+        !Number.isSafeInteger(item.maxRounds) ||
+        (item.maxRounds ?? 0) < 1 ||
+        typeof item.createdAt !== "string" ||
+        typeof item.updatedAt !== "string") {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        goalId: item.goalId,
+        revision: item.revision,
+        objective: item.objective.trim(),
+        phase: item.phase,
+        round: item.round,
+        maxRounds: item.maxRounds,
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+        ...(typeof item.lastTurnId === "string" && item.lastTurnId
+            ? { lastTurnId: item.lastTurnId }
+            : {}),
+        ...(typeof item.blocker === "string" && item.blocker.trim()
+            ? { blocker: item.blocker.trim() }
+            : {}),
+    };
+}
+export function projectCurrentGoal(events) {
+    let current = null;
+    for (const event of events) {
+        if (event.kind === "goal_cleared")
+            current = null;
+        if (event.kind === "goal_changed") {
+            const parsed = parseGoalSnapshot(event.data.goal);
+            if (parsed)
+                current = parsed;
+        }
+    }
+    return current ? cloneGoal(current) : null;
+}
+export function buildGoalCompactionInstructions(rawInstructions, goal) {
+    const reminder = goal
+        ? [
+            "Preserve this durable Goal snapshot in the compaction summary. Do not mark it complete or change its phase unless the Goal tool already did so:",
+            JSON.stringify(goal),
+        ].join("\n")
+        : undefined;
+    return [rawInstructions?.trim(), reminder]
+        .filter((item) => Boolean(item))
+        .join("\n\n") || undefined;
+}
+export function buildGoalContinuationContext(goal) {
+    if (!goal)
+        return undefined;
+    return [
+        "<current_goal>",
+        "This is the durable cross-turn Goal for this session. Continue working toward its objective without broadening user authorization.",
+        JSON.stringify(goal),
+        "Use get_goal to refresh it. Use update_goal with status=complete only when the objective is genuinely achieved and no required work remains; use blocked only when safe progress cannot continue.",
+        "</current_goal>",
+    ].join("\n");
+}
+export class GoalRegistry {
+    events;
+    armed = new Set();
+    modelCreateGrants = new Set();
+    constructor(events) {
+        this.events = events;
+    }
+    get(sessionId) {
+        const goal = projectCurrentGoal(this.events.snapshot(sessionId));
+        return goal ? { ...goal, armed: this.armed.has(sessionId) } : null;
+    }
+    startTurn(sessionId, userText) {
+        if (isExplicitGoalCreationRequest(userText))
+            this.modelCreateGrants.add(sessionId);
+        else
+            this.modelCreateGrants.delete(sessionId);
+    }
+    consumeModelCreateGrant(sessionId) {
+        const granted = this.modelCreateGrants.has(sessionId);
+        this.modelCreateGrants.delete(sessionId);
+        return granted;
+    }
+    create(input) {
+        let objective;
+        try {
+            objective = normalizeGoalObjective(input.objective);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: "GOAL_INVALID_INPUT",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        const existing = this.get(input.sessionId);
+        if (existing && existing.phase !== "complete") {
+            return {
+                ok: false,
+                code: "GOAL_ALREADY_EXISTS",
+                message: "an unfinished Goal already exists for this session",
+                goal: existing,
+            };
+        }
+        const maxRounds = Number.isSafeInteger(input.maxRounds)
+            ? Math.max(1, Math.min(128, input.maxRounds))
+            : DEFAULT_GOAL_MAX_ROUNDS;
+        const now = new Date().toISOString();
+        const goal = {
+            schemaVersion: 1,
+            goalId: randomUUID(),
+            revision: 1,
+            objective,
+            phase: "active",
+            round: 0,
+            maxRounds,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.events.append(input.sessionId, input.turnId ?? `${input.sessionId}:goal`, { kind: "goal_changed", data: { goal } });
+        if (input.arm !== false)
+            this.armed.add(input.sessionId);
+        return { ok: true, goal: { ...goal, armed: this.armed.has(input.sessionId) } };
+    }
+    update(input) {
+        const current = this.get(input.sessionId);
+        if (!current)
+            return { ok: false, code: "GOAL_NOT_FOUND", message: "Goal not found" };
+        if (current.goalId !== input.goalId)
+            return {
+                ok: false,
+                code: "GOAL_ID_CONFLICT",
+                message: "Goal id does not match the current session Goal",
+                goal: current,
+            };
+        if (current.revision !== input.expectedRevision)
+            return {
+                ok: false,
+                code: "GOAL_REVISION_CONFLICT",
+                message: `Goal revision changed: expected ${input.expectedRevision}, current ${current.revision}`,
+                goal: current,
+            };
+        let objective = current.objective;
+        if (input.objective !== undefined) {
+            try {
+                objective = normalizeGoalObjective(input.objective);
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    code: "GOAL_INVALID_INPUT",
+                    message: error instanceof Error ? error.message : String(error),
+                    goal: current,
+                };
+            }
+        }
+        const phase = input.phase ?? current.phase;
+        const blocker = typeof input.blocker === "string" ? input.blocker.trim().slice(0, 2_000) : "";
+        if (phase === "blocked" && !blocker && !current.blocker) {
+            return {
+                ok: false,
+                code: "GOAL_INVALID_INPUT",
+                message: "blocked Goal requires a concrete blocker",
+                goal: current,
+            };
+        }
+        const next = {
+            ...current,
+            revision: current.revision + 1,
+            objective,
+            phase,
+            updatedAt: new Date().toISOString(),
+            ...(phase === "blocked" && blocker
+                ? { blocker }
+                : current.blocker && phase === "blocked"
+                    ? { blocker: current.blocker }
+                    : {}),
+        };
+        delete next.armed;
+        if (phase !== "blocked")
+            delete next.blocker;
+        this.events.append(input.sessionId, input.turnId ?? current.lastTurnId ?? `${input.sessionId}:goal`, { kind: "goal_changed", data: { goal: next } });
+        if (phase !== "active" || input.arm === false)
+            this.armed.delete(input.sessionId);
+        else if (input.arm === true)
+            this.armed.add(input.sessionId);
+        return { ok: true, goal: { ...next, armed: this.armed.has(input.sessionId) } };
+    }
+    beginRound(input) {
+        const current = this.get(input.sessionId);
+        if (!current)
+            return { ok: false, code: "GOAL_NOT_FOUND", message: "Goal not found" };
+        if (current.round >= current.maxRounds) {
+            this.armed.delete(input.sessionId);
+            return {
+                ok: false,
+                code: "GOAL_ROUND_LIMIT",
+                message: `Goal reached its ${current.maxRounds}-round safety limit`,
+                goal: { ...current, armed: false },
+            };
+        }
+        if (current.goalId !== input.goalId)
+            return {
+                ok: false,
+                code: "GOAL_ID_CONFLICT",
+                message: "Goal id changed before the next round started",
+                goal: current,
+            };
+        if (current.revision !== input.expectedRevision)
+            return {
+                ok: false,
+                code: "GOAL_REVISION_CONFLICT",
+                message: `Goal revision changed: expected ${input.expectedRevision}, current ${current.revision}`,
+                goal: current,
+            };
+        const next = {
+            ...current,
+            revision: current.revision + 1,
+            round: current.round + 1,
+            lastTurnId: input.turnId,
+            updatedAt: new Date().toISOString(),
+        };
+        delete next.armed;
+        this.events.append(input.sessionId, input.turnId, {
+            kind: "goal_changed",
+            data: { goal: next },
+        });
+        return { ok: true, goal: { ...next, armed: this.armed.has(input.sessionId) } };
+    }
+    clear(input) {
+        const current = this.get(input.sessionId);
+        if (!current)
+            return { ok: false, code: "GOAL_NOT_FOUND", message: "Goal not found" };
+        if (current.goalId !== input.goalId || current.revision !== input.expectedRevision) {
+            return {
+                ok: false,
+                code: current.goalId !== input.goalId
+                    ? "GOAL_ID_CONFLICT"
+                    : "GOAL_REVISION_CONFLICT",
+                message: "Goal changed before it could be cleared",
+                goal: current,
+            };
+        }
+        this.armed.delete(input.sessionId);
+        this.events.append(input.sessionId, input.turnId ?? current.lastTurnId ?? `${input.sessionId}:goal`, { kind: "goal_cleared", data: {} });
+        return { ok: true, goal: { ...current, armed: false } };
+    }
+    arm(sessionId) {
+        const goal = this.get(sessionId);
+        if (!goal || goal.phase !== "active" || goal.round >= goal.maxRounds)
+            return goal;
+        this.armed.add(sessionId);
+        return { ...goal, armed: true };
+    }
+    disarm(sessionId) {
+        this.armed.delete(sessionId);
+        const goal = this.get(sessionId);
+        return goal ? { ...goal, armed: false } : null;
+    }
+    isArmed(sessionId) {
+        return this.armed.has(sessionId);
+    }
+    clearRuntime(sessionId) {
+        this.armed.delete(sessionId);
+        this.modelCreateGrants.delete(sessionId);
+    }
+}

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

@@ -42,6 +42,7 @@ import { resolveDefaultChatModel, resolveLowChatModel, } from "./model-resolver.
 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.
  *
@@ -66,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. */
@@ -259,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).
@@ -408,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
@@ -900,7 +1012,17 @@ export class ConsolePiRuntime {
         const pressureExtension = sessionId
             ? this.createContextPressureInlineExtension(sessionId)
             : undefined;
-        const extraFactories = [todoContextExtension, pressureExtension].filter((item) => Boolean(item));
+        const goalContextExtension = sessionId && this.options.goalRegistry
+            ? createGoalCompactionContextExtension({
+                sessionId,
+                registry: this.options.goalRegistry,
+            })
+            : undefined;
+        const extraFactories = [
+            todoContextExtension,
+            goalContextExtension,
+            pressureExtension,
+        ].filter((item) => Boolean(item));
         return {
             ...base,
             ...(extraFactories.length > 0
@@ -1318,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() {
@@ -1612,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 };
     }
     /**
@@ -2057,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,
@@ -2296,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;
@@ -2606,6 +2741,7 @@ export class ConsolePiRuntime {
     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);

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;
+    }
+}