humanish 0.113.0 → 0.114.0

package/dist/observer/render.js

@@ -12,12 +12,14 @@ import { loadAnalysis } from "../analysis/load.js";
 import { physicalCwdOf, runIdOf, bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { writeContainedOutputFile } from "../run/contained-output.js";
 import { loadRunBundlePrepared, readRunJsonIfExists } from "../run/locate.js";
+import { readRunNotes } from "../run/notes.js";
 import { RUN_STATUS_FILE } from "../run/status.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { renderObserverHtml } from "./artifact.js";
 import { buildObserverData } from "./data.js";
 import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin } from "./http.js";
 import { listenOnLoopback } from "./listen.js";
+import { createNotesWriter, NOTES_PATH } from "./notes-route.js";
 import { pinDirectChildDirectory, pinDirectory, readContainedFile, } from "./pinned-files.js";
 import { buildHistoryIndex, matchRunRoute, serveRunPath, writeResponse, } from "./run-routes.js";
 import { cli } from "../cli/invocation.js";
@@ -114,7 +116,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
     };
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "observer-data.json"), `${JSON.stringify(observerData, null, 2)}\n`, "utf8");
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "study-analysis.json"), `${JSON.stringify(analysis, null, 2)}\n`, "utf8");
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis }), "utf8");
+    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis, notes: await readRunNotes(preparedRunPaths) }), "utf8");
     await validatePreparedRunArtifactPaths(preparedRunPaths);
     const relativeObserverPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "index.html");
     const relativeObserverDataPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "observer-data.json");
@@ -180,6 +182,16 @@ async function resolveObserverRunSelection(cwd, runInput) {
         return null;
     return { runId: pointer.runId, runRoot, runsRoot };
 }
+/**
+ * The served run history. Exposed watch and selected-run viewers pass `onlyRun` and cannot
+ * enumerate other runs; full-library loopback viewers get the complete project index.
+ */
+async function writeHistory(response, proofRoot, onlyRun) {
+    const history = await buildHistoryIndex(proofRoot);
+    const runs = onlyRun === null ? history.runs : history.runs.filter((run) => run.runId === onlyRun);
+    const listed = onlyRun === null ? history : { latestRunId: runs.length > 0 ? onlyRun : null, runs };
+    writeResponse(response, 200, JSON.stringify(listed, null, 2), "application/json; charset=utf-8");
+}
 export async function serveObserver(result, options = {}) {
     if (!result.ok || !result.observerPath) {
         throw new Error("Cannot serve an observer result that did not render successfully.");
@@ -206,6 +218,14 @@ export async function serveObserver(result, options = {}) {
     const runtimeStreamUrls = () => observerRuntimeStreamUrls.get(result) ?? [];
     const exposed = options.exposed === true;
     const scopedToRun = exposed || options.scope === "run";
+    let port = 0;
+    // Notes are taken for the selected run only, whose paths this server already holds.
+    const notes = createNotesWriter({
+        exposed,
+        port: () => port,
+        resolveRun: async (runId) => (runId === result.run ? preparedRunPaths : null),
+        refresh: (prepared) => renderObserver(cwd, result.run, { open: false, expectedRun: prepared }),
+    });
     // Host allowlist for exposed mode (DNS-rebinding defense, identical to the run-library surface).
     // Seeded with the loopback names after bind; addPublicOrigin extends it with the tunnel/public-url
     // host. Never consulted in loopback (non-exposed) mode.
@@ -224,21 +244,22 @@ export async function serveObserver(result, options = {}) {
                 }
             }
             const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
+            if (url.pathname === NOTES_PATH) {
+                await notes.handle(request, response);
+                return;
+            }
+            // Adding a note is the only write; nothing else is read with another method.
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                writeResponse(response, 405, "Method Not Allowed", "text/plain; charset=utf-8");
+                return;
+            }
             if (url.pathname === "/") {
                 response.writeHead(302, { location: "/observer/index.html" });
                 response.end();
                 return;
             }
             if (url.pathname === "/_humanish/history.json") {
-                const history = await buildHistoryIndex(proofRoot);
-                // Exposed watch and selected-run viewers cannot enumerate other runs. Full-library
-                // loopback viewers retain the complete project index.
-                if (scopedToRun) {
-                    const attachedRuns = history.runs.filter((entry) => entry.runId === result.run);
-                    writeResponse(response, 200, JSON.stringify({ latestRunId: attachedRuns.length > 0 ? result.run : null, runs: attachedRuns }, null, 2), "application/json; charset=utf-8");
-                    return;
-                }
-                writeResponse(response, 200, JSON.stringify(history, null, 2), "application/json; charset=utf-8");
+                await writeHistory(response, proofRoot, scopedToRun ? result.run : null);
                 return;
             }
             if (url.pathname.startsWith("/_humanish/runs/")) {
@@ -257,10 +278,10 @@ export async function serveObserver(result, options = {}) {
                     writeResponse(response, 404, "Run not found", "text/plain; charset=utf-8");
                     return;
                 }
-                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runRoute.runId === result.run ? runtimeStreamUrls() : [], request);
+                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runRoute.runId === result.run ? runtimeStreamUrls() : [], request, runRoute.runId === result.run ? notes.pageToken(request) : undefined);
                 return;
             }
-            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls(), request);
+            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls(), request, notes.pageToken(request));
         }
         catch {
             writeResponse(response, 500, "Observer request failed", "text/plain; charset=utf-8");
@@ -269,7 +290,7 @@ export async function serveObserver(result, options = {}) {
     const server = createServer((request, response) => {
         void handleRequest(request, response);
     });
-    const port = await listenOnLoopback(server, options.port ?? 0);
+    port = await listenOnLoopback(server, options.port ?? 0);
     if (exposed) {
         hostAllowlist.add(`127.0.0.1:${port}`);
         hostAllowlist.add(`localhost:${port}`);
@@ -295,7 +316,10 @@ export async function serveObserver(result, options = {}) {
                 hostAllowlist.add(parsed.host);
             }
         },
-        close: () => closeServer(server),
+        close: async () => {
+            await notes.settled();
+            await closeServer(server);
+        },
     };
 }
 /**

package/dist/observer/run-routes.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import type { RunDisplay } from "../run/display.js";
 import { type ObserverData } from "./data.js";
 import { type PinnedDirectory } from "./pinned-files.js";
@@ -10,8 +11,13 @@ export interface ObserverRuntimeStreamUrl {
      *  evidence (keyframe replay/screenshot) instead of rendering "sandbox not found". */
     ended?: boolean;
 }
-/** internal: consumed by src/observer/serve.ts */
-export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">): Promise<void>;
+/** The run's artifact paths, only when they are still the pinned directory being served. */
+export declare function servedRunPaths(runRoot: PinnedDirectory): Promise<PreparedRunArtifactPaths>;
+/**
+ * internal: consumed by src/observer/serve.ts. `notesToken` goes into the run's Observer page so
+ * it can add notes; a server passes it only for a run it takes notes for.
+ */
+export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">, notesToken?: string): Promise<void>;
 /** internal: exported for the stream lifecycle tests. */
 export declare function withRuntimeStreamUrls(data: ObserverData, runtimeStreamUrls: ObserverRuntimeStreamUrl[]): ObserverData;
 /** internal: consumed by src/observer/serve.ts */

package/dist/observer/run-routes.js

@@ -9,6 +9,7 @@ import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
 import { isRunOutcome } from "../run/bundle-shape.js";
+import { decodeRunNote, listNoteEntries, MAX_NOTE_FILE_BYTES, noteListing, RUN_NOTES_DIR, runNoteFile, } from "../run/note-files.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
@@ -16,7 +17,7 @@ import { buildObserverData, recordedStreamEmbed, withObserverEndings, } from "./
 import { buildArtifactSecurityHeaders } from "./http.js";
 import { assertPinnedDirectory, openContainedFile, pinDirectChildDirectory, readContainedFile, relativeToRoot, sha256OfOpenedFile, } from "./pinned-files.js";
 /** The run's artifact paths, only when they are still the pinned directory being served. */
-async function servedRunPaths(runRoot) {
+export async function servedRunPaths(runRoot) {
     const runId = path.basename(runRoot.physicalPath);
     const cwd = path.dirname(path.dirname(path.dirname(runRoot.physicalPath)));
     const prepared = await bindExistingRunArtifactPaths(cwd, runId);
@@ -57,8 +58,40 @@ async function readServedAnalysisSpend(runRoot) {
         return undefined;
     }
 }
-/** internal: consumed by src/observer/serve.ts */
-export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request) {
+/**
+ * The run's reviewer notes as served: notes/ listed, and each note file read within
+ * MAX_NOTE_FILE_BYTES through the root's checks, so a --safe root's admission and hash checks
+ * apply to every note. A file that is not a readable note of the run is skipped and counted.
+ */
+async function readServedNotes(runRoot) {
+    const runId = path.basename(runRoot.physicalPath);
+    let listing;
+    try {
+        await assertPinnedDirectory(runRoot);
+        listing = await listNoteEntries(path.join(runRoot.physicalPath, RUN_NOTES_DIR));
+    }
+    catch {
+        return { runId, notes: [], skipped: [`${RUN_NOTES_DIR} is not a plain folder.`] };
+    }
+    if (listing === null)
+        return { runId, notes: [], skipped: [] };
+    const { ids, skipped } = noteListing(listing);
+    const notes = [];
+    for (const id of ids) {
+        const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, runNoteFile(id)), { maxBytes: MAX_NOTE_FILE_BYTES });
+        const note = bytes === null ? null : decodeRunNote(bytes, runId, id);
+        if (note === null)
+            skipped.push(`${runNoteFile(id)} was skipped.`);
+        else
+            notes.push(note);
+    }
+    return { runId, notes, skipped };
+}
+/**
+ * internal: consumed by src/observer/serve.ts. `notesToken` goes into the run's Observer page so
+ * it can add notes; a server passes it only for a run it takes notes for.
+ */
+export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request, notesToken) {
     const root = runRoot.physicalPath;
     const filePath = path.resolve(root, relativePath === "" ? "observer/index.html" : relativePath);
     if (!isPathInside(root, filePath)) {
@@ -87,7 +120,12 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
-        writeResponse(response, 200, renderObserverHtml(observerData, { analysis }), "text/html; charset=utf-8");
+        const notes = await readServedNotes(runRoot);
+        writeResponse(response, 200, renderObserverHtml(observerData, {
+            analysis,
+            notes,
+            ...(notesToken === undefined ? {} : { notesToken }),
+        }), "text/html; charset=utf-8");
         return;
     }
     if (cleanedRelativePath === "observer/observer-data.json") {
@@ -103,7 +141,10 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 200, JSON.stringify(await readObserverAnalysis(runRoot)), "application/json; charset=utf-8");
         return;
     }
-    if (path.extname(filePath).toLowerCase() === ".mp4") {
+    // Every file under notes/ is read within the note limit, whatever its name, so media handling
+    // never streams one.
+    const notePath = derivedRoot === RUN_NOTES_DIR;
+    if (!notePath && path.extname(filePath).toLowerCase() === ".mp4") {
         await serveContainedMedia(runRoot, filePath, response, request);
         return;
     }
@@ -112,7 +153,7 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     try {
-        const body = await readContainedFile(runRoot, filePath);
+        const body = await readContainedFile(runRoot, filePath, notePath ? { maxBytes: MAX_NOTE_FILE_BYTES } : {});
         if (!body) {
             writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
             return;

package/dist/observer/serve.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type NotesWriter } from "./notes-route.js";
 import type { PinnedDirectory } from "./pinned-files.js";
 import { type AdmittedRun } from "./run-inventory.js";
 import type { LibraryHistory } from "./library.js";
@@ -70,6 +71,8 @@ export declare function createShareSafetyAdmission(cwd: string, options?: {
 }): ShareSafetyAdmission;
 export interface ServeRequestHandlerOptions {
     proofRoot: PinnedDirectory;
+    /** Takes reviewer notes on loopback; without it the library refuses them. */
+    notes?: NotesWriter;
     safe: boolean;
     admit: (runId: string) => Promise<AdmittedRun | null>;
     hostAllowlist: ReadonlySet<string>;

package/dist/observer/serve.js

@@ -3,7 +3,9 @@ import { runNotFoundMessage } from "../run/run-not-found.js";
 import { createServer } from "node:http";
 import path from "node:path";
 import { pinDirectChildDirectory, pinDirectory } from "./pinned-files.js";
-import { buildHistoryIndex, matchRunRoute, serveRunPath } from "./run-routes.js";
+import { createNotesWriter, NOTES_PATH } from "./notes-route.js";
+import { renderObserver } from "./render.js";
+import { buildHistoryIndex, matchRunRoute, servedRunPaths, serveRunPath } from "./run-routes.js";
 import { hashRunInventory, inventoryRoot, readRunInventory, } from "./run-inventory.js";
 import { renderLibraryHtml } from "./library.js";
 import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin, } from "./http.js";
@@ -104,6 +106,13 @@ export function createServeRequestHandler(options) {
             for (const [name, value] of Object.entries(buildServeSecurityHeaders())) {
                 response.setHeader(name, value);
             }
+            if (new URL(request.url ?? "/", "http://127.0.0.1").pathname === NOTES_PATH) {
+                if (options.notes)
+                    await options.notes.handle(request, response);
+                else
+                    writeText(response, 405, "Method Not Allowed");
+                return;
+            }
             const method = request.method ?? "GET";
             if (method !== "GET" && method !== "HEAD") {
                 writeText(response, 405, "Method Not Allowed");
@@ -161,7 +170,7 @@ export function createServeRequestHandler(options) {
                 }
                 // The explicit empty runtimeStreamUrls keeps a future refactor from
                 // reintroducing auth-keyed stream injection on the serve surface.
-                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, [], request);
+                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, [], request, options.notes?.pageToken(request));
                 return;
             }
             writeText(response, 404, "Not found");
@@ -260,8 +269,24 @@ export async function serveObserverLibrary(cwdInput, options) {
     }
     const declaredOrigin = options.publicOrigin ? parsePublicOrigin(options.publicOrigin) : null;
     const hostAllowlist = new Set();
+    let port = 0;
+    const notes = createNotesWriter({
+        exposed: mode !== "loopback",
+        port: () => port,
+        resolveRun: async (runId) => {
+            const pinned = await pinDirectChildDirectory(proofRoot, runId);
+            if (!pinned || (options.safe && (await admission.admit(runId)) === null))
+                return null;
+            return servedRunPaths(pinned);
+        },
+        refresh: (prepared) => renderObserver(cwd, path.basename(prepared.physicalRunRoot), {
+            open: false,
+            expectedRun: prepared,
+        }),
+    });
     const handler = createServeRequestHandler({
         proofRoot,
+        notes,
         safe: options.safe,
         admit: (runId) => admission.admit(runId),
         hostAllowlist,
@@ -276,7 +301,6 @@ export async function serveObserverLibrary(cwdInput, options) {
     const server = createServer((request, response) => {
         void handler(request, response);
     });
-    let port;
     try {
         port = await listenOnLoopback(server, options.port);
     }
@@ -314,6 +338,7 @@ export async function serveObserverLibrary(cwdInput, options) {
                 hostAllowlist.add(parsed.host);
             },
             close: async () => {
+                await notes.settled();
                 const closed = closeServer(server);
                 // Keep-alive sockets would otherwise keep close() pending past the point
                 // the operator believes Ctrl-C tore the server down.