humanish 0.125.0 → 0.126.0

package/dist/cli/commands/study.js

@@ -2,6 +2,8 @@ import { formatAutomaticAnalysisBudget } from "../../analysis/automatic-config.j
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
+import { describeTimeZones } from "../../study/plan-participants.js";
+import { plannedParticipants } from "../../study/warnings.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
 export function registerStudyCommands(parent, io) {
@@ -120,6 +122,7 @@ function formatStudyShowHuman(result) {
         ...(result.path ? [`path: ${result.path}`] : []),
         ...(result.origin ? [`origin: ${result.origin}`] : []),
         ...(config.subject.repos?.length ? [`repos: ${config.subject.repos.join(", ")}`] : []),
+        ...timeZoneLines(config),
         ...(result.personas ?? []).map((persona) => `persona ${persona.id}: ${persona.brief ? `authored context (before runtime additions)\n${persona.brief.text}` : "unresolved; id only"}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
@@ -145,3 +148,8 @@ function formatStudyCheckHuman(result) {
     ].join("\n") + "\n";
     return result.error === undefined ? stdout : { stdout, error: result.error };
 }
+/** The `time zones:` line, for a study whose participants declare a time zone. */
+function timeZoneLines(config) {
+    const zones = describeTimeZones(plannedParticipants(config));
+    return zones === undefined ? [] : [`time zones: ${zones}`];
+}

package/dist/evidence/redaction.d.ts

@@ -8,6 +8,7 @@ export declare const REDACTION_MARKERS: {
     readonly runtimePath: "[REDACTED_RUNTIME_PATH]";
     readonly promptText: "[REDACTED_PROMPT_TEXT]";
     readonly lobbyCode: "[REDACTED_LOBBY_CODE]";
+    readonly urlPart: "[REDACTED_URL_PART]";
 };
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export declare function sensitivePatterns(): readonly RegExp[];

package/dist/evidence/redaction.js

@@ -136,6 +136,7 @@ export const REDACTION_MARKERS = {
     runtimePath: "[REDACTED_RUNTIME_PATH]",
     promptText: "[REDACTED_PROMPT_TEXT]",
     lobbyCode: "[REDACTED_LOBBY_CODE]",
+    urlPart: "[REDACTED_URL_PART]",
 };
 const LOCAL_PATH_PATTERNS = [
     [/\/private\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],

package/dist/evidence/trace-page.d.ts

@@ -0,0 +1,6 @@
+import type { TracePage } from "../actors/contract.js";
+/**
+ * The page of an observed URL, or undefined when there is none or the URL parser rejects it.
+ * `redact` is the trace's text redaction (the run's known-value scrub, then redactText).
+ */
+export declare function tracePage(url: string | undefined, redact: (text: string) => string): TracePage | undefined;

package/dist/evidence/trace-page.js

@@ -0,0 +1,90 @@
+import { readingsOf, scanEncodedText } from "./encoded-text.js";
+import { REDACTION_MARKERS } from "./redaction.js";
+// The page a computer-use observation was on, as a trace records it: the URL's origin and path,
+// with no query string, fragment or user info, and any path segment that can carry a credential or
+// an address withheld. See docs/contracts/schemas.md#actor-trace.
+const WEB_SCHEMES = new Set(["http:", "https:"]);
+// The longest path a page keeps, its truncation marker included.
+const MAX_PATH = 1024;
+const TRUNCATED = "[TRUNCATED]";
+// A percent-encoded unreserved character (a letter, digit, `-`, `.`, `_` or `~`) or `%` itself.
+// RFC 3986 section 2.3 says producers should not encode the first, and an encoded `%` is an
+// encoding nested in another, so either only hides text from a literal match: the run's
+// sandbox-id scrub, verify's raw-id check, a study secret's scrub.
+const ENCODED_TO_HIDE = /%(?:3[0-9]|4[1-9A-F]|5[0-9AF]|6[1-9A-F]|7[0-9AE]|2[5DE])/i;
+const EMAIL = /[^\s@/]@[^\s@/.]+\.[^\s@/]/;
+// 16 characters is the floor redactText uses for a credential parameter's value. Each open-ended
+// repeat is written `[...]{n}[...]*`, as in redaction.ts, so a megabyte path costs linear time.
+const TOKEN_RUN = /[A-Za-z0-9_-]{16}[A-Za-z0-9_-]*/g;
+const LETTER = /[A-Za-z]/;
+const DIGIT = /[0-9]/;
+/**
+ * A run of 16 or more letters, digits, `-` and `_` in which some piece between separators is 8 or
+ * more characters long and mixes letters and digits: UUIDs, hex digests, base64url tokens and
+ * sandbox ids. A slug's pieces are words or numbers, so `how-to-build-a-thing-2024` stays.
+ */
+function tokenShaped(text) {
+    for (const [run] of text.matchAll(TOKEN_RUN))
+        for (const piece of run.split(/[-_]/))
+            if (piece.length >= 8 && LETTER.test(piece) && DIGIT.test(piece))
+                return true;
+    return false;
+}
+/** A segment is withheld when any reading of it holds an address, a token or redactable text. */
+function withheld(segment, redact) {
+    if (ENCODED_TO_HIDE.test(segment))
+        return true;
+    return readingsOf(segment).some((reading) => EMAIL.test(reading) || tokenShaped(reading) || redact(reading) !== reading);
+}
+/**
+ * Each withheld segment as the marker, then the trace redaction over the whole path for patterns
+ * that span segments, then the cut. A path verify's trace scan would still read as sensitive or
+ * opaque is withheld whole, so a page never changes a run's grade.
+ */
+function redactPath(pathname, redact) {
+    const segments = pathname
+        .split("/")
+        .map((segment) => (withheld(segment, redact) ? REDACTION_MARKERS.urlPart : segment));
+    const redacted = redact(segments.join("/"));
+    // Cut after redaction: a cut first could shorten a token below the length the rules match.
+    const path = redacted.length > MAX_PATH
+        ? `${redacted.slice(0, MAX_PATH - TRUNCATED.length)}${TRUNCATED}`
+        : redacted;
+    const scan = scanEncodedText(path);
+    return scan.sensitive || scan.opaque ? REDACTION_MARKERS.urlPart : path;
+}
+/**
+ * The origin with each token-shaped host label withheld, since a tunnel or preview host can be as
+ * unguessable as a shared link, then through the trace redaction, which withholds a sandbox host
+ * whole.
+ */
+function redactOrigin(url, redact) {
+    if (url.hostname.startsWith("["))
+        return redact(url.origin);
+    const host = url.hostname
+        .split(".")
+        .map((label) => (tokenShaped(label) ? REDACTION_MARKERS.urlPart : label))
+        .join(".");
+    return redact(`${url.protocol}//${host}${url.port === "" ? "" : `:${url.port}`}`);
+}
+/**
+ * The page of an observed URL, or undefined when there is none or the URL parser rejects it.
+ * `redact` is the trace's text redaction (the run's known-value scrub, then redactText).
+ */
+export function tracePage(url, redact) {
+    if (url === undefined)
+        return undefined;
+    const parsed = URL.parse(url);
+    if (parsed === null)
+        return undefined;
+    // A non-web URL keeps its scheme only: a file: path or a data: payload never lands.
+    if (!WEB_SCHEMES.has(parsed.protocol))
+        return { origin: parsed.protocol, path: "" };
+    const origin = redactOrigin(parsed, redact);
+    const path = redactPath(parsed.pathname, redact);
+    // A study secret can span both parts, such as a whole invite link, which neither part holds.
+    const joined = `${origin}${path}`;
+    if (redact(joined) !== joined)
+        return { origin: REDACTION_MARKERS.urlPart, path: REDACTION_MARKERS.urlPart };
+    return { origin, path };
+}

package/dist/observer/feed-cursors.d.ts

@@ -0,0 +1,14 @@
+import type { LiveItemsCursor } from "../run/live-items.js";
+import type { LiveItemsRead } from "../run/stream-trace.js";
+import type { ObserverItems } from "./participant-items.js";
+/**
+ * The prefixes a poll's `after` parameter says the page holds, by live file path. A parameter with
+ * a cursor that is not spelled as the server spells them, more than 10,000 cursors, or two for one
+ * file is ignored whole, so the page gets every list in full.
+ */
+export declare function parseFeedCursors(after: string | null): ReadonlyMap<string, LiveItemsCursor>;
+/**
+ * `items` with each live file's cursor on the entry of the stream it was joined into, and
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ */
+export declare function withFeedCursors(items: ObserverItems, live: readonly LiveItemsRead[]): ObserverItems;

package/dist/observer/feed-cursors.js

@@ -0,0 +1,61 @@
+// The cursors of the Observer's feed. A cursor is `<position>.<generation>.<items>.<bytes>`: the
+// live file live/<position>.<generation>.ndjson (src/run/live-items.ts names them) and the prefix of
+// it a page holds. Each feed response gives a running participant's cursor as `live`; the page sends
+// the cursors back in `after` and compares them only as strings, so a cursor has one spelling:
+// decimal integers without leading zeros.
+/** A live file's stem, `<position>.<generation>`, as isLiveItemsIndex accepts its path. */
+const LIVE_PATH = /^live\/([1-9]\d{0,5}\.[1-9]\d{0,8})\.ndjson$/;
+/** A cursor: the stem, then the line and byte counts. */
+const CURSOR = /^([1-9]\d{0,5}\.[1-9]\d{0,8})\.(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})$/;
+/** More cursors than any page sends: a run has one live file per participant. */
+const MAX_CURSORS = 10_000;
+/**
+ * The prefixes a poll's `after` parameter says the page holds, by live file path. A parameter with
+ * a cursor that is not spelled as the server spells them, more than 10,000 cursors, or two for one
+ * file is ignored whole, so the page gets every list in full.
+ */
+export function parseFeedCursors(after) {
+    const cursors = new Map();
+    if (after === null || after === "")
+        return cursors;
+    const parts = after.split(",", MAX_CURSORS + 1);
+    if (parts.length > MAX_CURSORS)
+        return new Map();
+    for (const part of parts) {
+        const match = CURSOR.exec(part);
+        const path = `live/${match?.[1]}.ndjson`;
+        const cursor = { items: Number(match?.[2]), bytes: Number(match?.[3]) };
+        if (match === null ||
+            !Number.isSafeInteger(cursor.items) ||
+            !Number.isSafeInteger(cursor.bytes) ||
+            cursors.has(path))
+            return new Map();
+        cursors.set(path, cursor);
+    }
+    return cursors;
+}
+/** The cursor at `items` lines and `bytes` bytes into the live file at `path`. */
+function cursorText(path, position) {
+    const stem = LIVE_PATH.exec(path)?.[1];
+    if (stem === undefined)
+        throw new Error(`${path} is not a live file name.`);
+    return `${stem}.${position.items}.${position.bytes}`;
+}
+/**
+ * `items` with each live file's cursor on the entry of the stream it was joined into, and
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ */
+export function withFeedCursors(items, live) {
+    const streams = Object.assign(Object.create(null), items.streams);
+    for (const read of live) {
+        const entry = Object.hasOwn(streams, read.streamId) ? streams[read.streamId] : undefined;
+        if (entry === undefined || !Array.isArray(entry.liveActor))
+            continue;
+        streams[read.streamId] = {
+            ...entry,
+            live: cursorText(read.index.path, read.index),
+            ...(read.after === undefined ? {} : { liveAfter: cursorText(read.index.path, read.after) }),
+        };
+    }
+    return { ...items, streams };
+}

package/dist/observer/participant-items.d.ts

@@ -23,6 +23,13 @@ export interface ObserverItems {
         actor?: ActorTraceItem[];
         liveActor?: ActorTraceItem[];
         artifacts?: ObserverStream["artifacts"];
+        /**
+         * Where `liveActor` ends in the participant's live file, as a cursor the page sends back
+         * (src/observer/feed-cursors.ts). Only on a feed response, for a list read from a live file.
+         */
+        live?: string;
+        /** Set when `liveActor` holds only the items past this cursor, one the page sent. */
+        liveAfter?: string;
     }>;
 }
 /** The data as observer-data.json and the page's items carry it. */

package/dist/observer/pinned-files.d.ts

@@ -18,11 +18,12 @@ export interface PinnedDirectory {
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
  * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
- * a shorter file.
+ * a shorter file; with `start` as well, the bytes from `start` to `length`.
  */
 export declare function readContainedFile(root: PinnedDirectory, filePathInput: string, options?: {
     maxBytes?: number;
     length?: number;
+    start?: number;
 }): Promise<Buffer | null>;
 export declare function openContainedFile(root: PinnedDirectory, filePathInput: string): Promise<{
     handle: FileHandle;

package/dist/observer/pinned-files.js

@@ -11,7 +11,7 @@ import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
  * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
- * a shorter file.
+ * a shorter file; with `start` as well, the bytes from `start` to `length`.
  */
 export async function readContainedFile(root, filePathInput, options = {}) {
     const opened = await openContainedFile(root, filePathInput);
@@ -19,7 +19,7 @@ export async function readContainedFile(root, filePathInput, options = {}) {
         return null;
     try {
         const body = options.length !== undefined
-            ? await readOpenedPrefix(opened.handle, options.length)
+            ? await readOpenedPrefix(opened.handle, options.length, options.start)
             : options.maxBytes === undefined
                 ? await opened.handle.readFile()
                 : opened.size > options.maxBytes

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

@@ -17,7 +17,7 @@ export declare function servedRunPaths(runRoot: PinnedDirectory): Promise<Prepar
  * 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>;
+export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers" | "url">, 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

@@ -10,12 +10,13 @@ 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 { displayedTraces, loadStreamTraces } from "../run/stream-trace.js";
+import { displayedTraces, loadStreamTraces, } from "../run/stream-trace.js";
 import { isNodeError, isRecord } from "../run/type-guards.js";
 import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } 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";
+import { parseFeedCursors, withFeedCursors } from "./feed-cursors.js";
 import { splitObserverData } from "./participant-items.js";
 import { buildObserverData, observerDataFromSaved, recordedStreamEmbed, withObserverEndings, } from "./data.js";
 import { buildArtifactSecurityHeaders } from "./http.js";
@@ -103,14 +104,14 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     if (cleanedRelativePath === "observer/index.html") {
-        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
-        if ("unavailable" in observerData) {
-            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
+        const observed = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observed) {
+            writeResponse(response, 404, `Observer data not found: ${observed.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
         const notes = await readRunNotes(servedNoteFiles(runRoot));
-        writeResponse(response, 200, renderObserverHtml(observerData, {
+        writeResponse(response, 200, renderObserverHtml(observed.data, {
             analysis,
             notes,
             ...(notesToken === undefined ? {} : { notesToken }),
@@ -121,15 +122,17 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     // polls observer-feed.json, the same data with the items, so one projection serves each poll.
     if (cleanedRelativePath === "observer/observer-data.json" ||
         cleanedRelativePath === "observer/observer-feed.json") {
-        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
-        if ("unavailable" in observerData) {
-            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
+        const observed = await observerDataOrReason(runRoot, runtimeStreamUrls, cleanedRelativePath === "observer/observer-feed.json"
+            ? requestedCursors(runRoot, request)
+            : undefined);
+        if ("unavailable" in observed) {
+            writeResponse(response, 404, `Observer data not found: ${observed.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
-        const { shell, items } = splitObserverData(observerData);
+        const { shell, items } = splitObserverData(observed.data);
         writeResponse(response, 200, cleanedRelativePath === "observer/observer-data.json"
             ? JSON.stringify(shell, null, 2)
-            : JSON.stringify({ data: shell, items }), "application/json; charset=utf-8");
+            : JSON.stringify({ data: shell, items: withFeedCursors(items, observed.live) }), "application/json; charset=utf-8");
         return;
     }
     if (cleanedRelativePath === "observer/study-analysis.json") {
@@ -163,19 +166,31 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
     }
 }
+/**
+ * The live cursors a feed poll sends in `after`. A root that checks reads against admitted files
+ * and digests gets none: its digest check covers whole files, and it serves only finished runs.
+ */
+function requestedCursors(runRoot, request) {
+    if (runRoot.admitsFile !== undefined ||
+        runRoot.admitsContent !== undefined ||
+        request?.url === undefined)
+        return undefined;
+    return parseFeedCursors(new URL(request.url, "http://observer.invalid").searchParams.get("after"));
+}
 /** The run's trace files, read through its pinned folder. */
 function pinnedTraceReader(runRoot) {
-    return async (relativePath, maxBytes, length) => {
+    return async (relativePath, maxBytes, length, start) => {
         const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), {
             maxBytes,
             ...(length === undefined ? {} : { length }),
+            ...(start === undefined ? {} : { start }),
         }).catch(() => null);
         return bytes === null ? { refused: `${relativePath} could not be read` } : { bytes };
     };
 }
 async function readObserverData(runRoot, runtimeStreamUrls = []) {
     const read = await observerDataOrReason(runRoot, runtimeStreamUrls);
-    return "unavailable" in read ? null : read;
+    return "unavailable" in read ? null : read.data;
 }
 /**
  * The run's Observer data, or why there is none. run.json is the source: each trace is loaded
@@ -185,7 +200,7 @@ async function readObserverData(runRoot, runtimeStreamUrls = []) {
  * cannot be read, parsed or used as a bundle (which a browser poll can meet mid-write) gives the
  * reason, a 404 the poller retries, never the saved projection.
  */
-async function observerDataOrReason(runRoot, runtimeStreamUrls) {
+async function observerDataOrReason(runRoot, runtimeStreamUrls, cursors) {
     const record = await readLocalRunStatus(runRoot);
     const runJson = path.join(runRoot.physicalPath, "run.json");
     const bundleBytes = await readContainedFile(runRoot, runJson).catch(() => null);
@@ -194,8 +209,10 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls) {
     // A root admitted for safe serving checks every read against the identity and digest admitted
     // with the run's share_ready verification, so a run.json changed since then is refused, and the
     // saved projection it may serve is the one admitted with the verified run.
-    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined))
-        return savedObserverData(runRoot, record, runtimeStreamUrls);
+    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined)) {
+        const saved = await savedObserverData(runRoot, record, runtimeStreamUrls);
+        return "unavailable" in saved ? saved : { data: saved, live: [] };
+    }
     if (bundleBytes === null)
         return { unavailable: "run.json is there but could not be read: it is a link or changed." };
     let stored;
@@ -209,8 +226,12 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls) {
         return { unavailable: "run.json is not a run bundle; it may be mid-write, so try again." };
     }
     try {
-        const bundle = displayedTraces(await loadStreamTraces(pinnedTraceReader(runRoot), stored));
-        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
+        const loaded = await loadStreamTraces(pinnedTraceReader(runRoot), stored, cursors === undefined ? {} : { liveAfter: (index) => cursors.get(index.path) });
+        const bundle = displayedTraces(loaded);
+        return {
+            data: withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls),
+            live: loaded.live,
+        };
     }
     catch {
         return { unavailable: "run.json could not be shown as a run." };