humanish 0.113.0 → 0.115.0

package/dist/run/notes.js

@@ -0,0 +1,192 @@
+// Reviewer notes: free text a person adds at a moment of a recorded run. Each note is its own file
+// in the run directory (note-files.ts). A note's time counts from the run clock's start, the
+// first timed capture or desktop video of any participant, which is the Observer's study clock.
+import { cli } from "../cli/invocation.js";
+import { redactText } from "../evidence/redaction.js";
+import { createContainedOutputFile } from "./contained-output.js";
+import { loadRunBundlePrepared } from "./locate.js";
+import { countRunNotes, encodeRunNote, newRunNoteId, runNoteFile } from "./note-files.js";
+import { MAX_NOTE_TEXT, MAX_RUN_NOTES } from "./note-shape.js";
+import { runParticipantCaptions, streamParticipantIdOf } from "./participant-records.js";
+import { physicalCwdOf, runIdOf } from "./paths.js";
+import { transientCommsKnownValueScrub } from "./transient-comms-secrets.js";
+import { isNodeError } from "./type-guards.js";
+const DEFAULT_AUTHOR = "you";
+/** New ids a note tries when the one before was taken. */
+const PUBLISH_ATTEMPTS = 5;
+const refuse = (code, message) => ({
+    ok: false,
+    error: { code, message },
+});
+/**
+ * The stream id a note's participant names: a stream id, or the participant's own id from the study
+ * (`charge-nurse`). Both kinds of id are matched, so a name that is one stream's id and another
+ * stream's study id is refused, naming both, as is a study id that two streams record. Otherwise
+ * the refusal names the run's participants by caption, with the id to type for each.
+ */
+function participantStreamId(bundle, named) {
+    const captions = runParticipantCaptions(bundle);
+    const matching = bundle.streams.filter((stream) => stream.id === named || streamParticipantIdOf(stream) === named);
+    if (matching.length === 1)
+        return matching[0].id;
+    const described = (stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        return `${captions.get(stream.id)} (stream id ${stream.id}${participantId === undefined ? "" : `, study id ${participantId}`})`;
+    };
+    if (matching.length > 1)
+        return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `${named} names ${matching.length} participants in run ${bundle.runId}: ${matching.map(described).join(" and ")}. Name the one you mean by an id only it has.`);
+    const known = bundle.streams.map((stream) => `${captions.get(stream.id)} (${streamParticipantIdOf(stream) ?? stream.id})`);
+    return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `Run ${bundle.runId} has no participant ${named}. Its participants are ${known.join(", ")}; leave the participant out for a note on the whole run.`);
+}
+/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
+export function formatRunTime(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}`;
+}
+/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
+export function runClock(bundle) {
+    const moments = bundle.streams.flatMap((stream) => [
+        ...(captureTimes(stream) ?? []),
+        ...recordingMoments(stream),
+    ]);
+    if (moments.length === 0)
+        return null;
+    // A loop, since spreading a long recording's capture times into Math.min can overflow the stack.
+    let startMs = Infinity;
+    let endMs = -Infinity;
+    for (const moment of moments) {
+        startMs = Math.min(startMs, moment);
+        endMs = Math.max(endMs, moment);
+    }
+    return { startMs, endMs };
+}
+function traceItems(stream) {
+    return stream.actor?.items ?? stream.liveActor?.items ?? [];
+}
+const stamp = (item) => item.at === undefined ? Number.NaN : Date.parse(item.at);
+/**
+ * A participant's capture times, as the Observer's study clock reads them: only when every capture
+ * is stamped and the stamps never go back. Otherwise the participant adds nothing to the clock.
+ */
+function captureTimes(stream) {
+    const times = traceItems(stream)
+        .filter((item) => (item.kind === "screenshot" || item.kind === "ui_action") && item.screenshotRef)
+        .map(stamp);
+    const ordered = times.every((time, index) => Number.isFinite(time) && (index === 0 || time >= times[index - 1]));
+    return ordered ? times : null;
+}
+function recordingMoments(stream) {
+    const recording = stream.recording;
+    if (!recording)
+        return [];
+    const startMs = Date.parse(recording.startedAt);
+    const endMs = startMs + recording.durationMs;
+    return Number.isFinite(startMs) && Number.isFinite(endMs) && recording.durationMs > 0
+        ? [startMs, endMs]
+        : [];
+}
+/** The latest stamped trace item at or before `moment`, among the given participants. */
+function nearestItem(streams, moment) {
+    let best = null;
+    for (const stream of streams)
+        for (const item of traceItems(stream)) {
+            const time = stamp(item);
+            if (Number.isFinite(time) && time <= moment && (best === null || time >= best.time))
+                best = { participant: stream.id, itemId: item.id, time };
+        }
+    return best === null ? null : { participant: best.participant, itemId: best.itemId };
+}
+/**
+ * The text as it is written: line breaks as `\n`, the run's known values and every secret-shaped
+ * value or local path replaced, as other run text is before it is written.
+ */
+function scrubNoteText(text) {
+    let known;
+    try {
+        known = transientCommsKnownValueScrub()(text);
+    }
+    catch {
+        // A closed run scope refuses to scrub and has dropped its values. The note then gets the
+        // pattern redaction that a separate `humanish notes` process gives it.
+        known = text;
+    }
+    return redactText(known.replace(/\r\n?/g, "\n").trim());
+}
+/** Why the text cannot be a note, or null when it can. */
+function noteTextProblem(text) {
+    if (text.length === 0)
+        return "A note needs some text.";
+    if (text.length > MAX_NOTE_TEXT)
+        return `A note holds at most ${MAX_NOTE_TEXT} characters; this one has ${text.length}. Shorten it and add it again.`;
+    if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(text))
+        return "A note holds plain text and line breaks; this one has a control character. Remove it and add the note again.";
+    return null;
+}
+/**
+ * Adds a note as a new file, notes/<id>.json, created under a name nothing holds. It reads no other
+ * note and replaces nothing, so notes added at the same time, from any process, are all kept.
+ */
+export async function addRunNote(prepared, input) {
+    const text = scrubNoteText(input.text);
+    const problem = noteTextProblem(text);
+    if (problem)
+        return refuse("HUMANISH_NOTE_INVALID", problem);
+    let loaded;
+    try {
+        loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared);
+    }
+    catch (error) {
+        // The storage check throws on a link or a special file anywhere in the run directory, or on a
+        // run directory that moved.
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `No note was added to run ${runIdOf(prepared)}: its directory failed humanish's storage check. ${error instanceof Error ? error.message : String(error)} Fix that in the run directory and add the note again.`);
+    }
+    if (!loaded)
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`${cli(`verify --run ${runIdOf(prepared)}`)}\` says what is wrong with it.`);
+    const { bundle } = loaded;
+    const clock = runClock(bundle);
+    if (!clock)
+        return refuse("HUMANISH_NOTE_NO_CLOCK", `Run ${bundle.runId} has no captures with recorded times, so a note cannot point at a moment of it.`);
+    const participant = input.participant === null ? null : participantStreamId(bundle, input.participant);
+    if (participant !== null && typeof participant !== "string")
+        return participant;
+    // The Observer shows whole seconds, so a moment in the second the clock ends is its end.
+    const durationMs = clock.endMs - clock.startMs;
+    if (!Number.isFinite(input.atMs) ||
+        input.atMs < 0 ||
+        Math.floor(input.atMs / 1000) > Math.floor(durationMs / 1000))
+        return refuse("HUMANISH_NOTE_OUTSIDE_RUN", `A note on run ${bundle.runId} needs a moment from 00:00 to ${formatRunTime(durationMs)}, the time its captures cover.`);
+    const atMs = Math.min(Math.round(input.atMs), durationMs);
+    const streams = bundle.streams.filter((stream) => participant === null || stream.id === participant);
+    const now = new Date();
+    const fields = {
+        atMs,
+        participant,
+        nearest: nearestItem(streams, clock.startMs + atMs),
+        text,
+        author: DEFAULT_AUTHOR,
+        createdAt: now.toISOString(),
+        editedAt: null,
+    };
+    try {
+        // A count of the files notes/ lists; no note is read.
+        if ((await countRunNotes(prepared)) >= MAX_RUN_NOTES)
+            return refuse("HUMANISH_NOTES_FULL", `Run ${bundle.runId} already has ${MAX_RUN_NOTES} notes, the most one run keeps.`);
+        // The note appears only under a name nothing holds; a taken name gets a new id.
+        for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt += 1) {
+            const note = { id: newRunNoteId(now), ...fields };
+            try {
+                await createContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+            return { ok: true, note, scrubbed: text !== input.text.replace(/\r\n?/g, "\n").trim() };
+        }
+    }
+    catch {
+        return refuse("HUMANISH_NOTES_UNREADABLE", `The notes folder in run ${bundle.runId} is not a plain folder inside the run, so no note was added. Move it out of the run directory and add the note again.`);
+    }
+    return refuse("HUMANISH_NOTE_ID_TAKEN", `Each new id humanish chose for the note was already taken in run ${bundle.runId}'s notes folder, so no note was added. Something else is writing files there; add the note again.`);
+}

package/dist/run/participant-caption.d.ts

@@ -29,3 +29,12 @@ export interface SavedCaptionFacts {
  * recorded persona; a scripted mobile surface also identifies a phone.
  */
 export declare function savedCaption(stream: SavedCaptionFacts): string;
+/** A saved stream, as much of it as `streamCaptions` reads. */
+export interface CaptionedStream extends SavedCaptionFacts {
+    readonly id: string;
+}
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export declare function streamCaptions(streams: readonly CaptionedStream[]): Map<string, string>;

package/dist/run/participant-caption.js

@@ -58,3 +58,22 @@ export function savedCaption(stream) {
     }
     return label;
 }
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export function streamCaptions(streams) {
+    const repeated = (labels) => new Set(labels.filter((label, index) => labels.indexOf(label) !== index));
+    const saved = streams.map(savedCaption);
+    const savedTwice = repeated(saved);
+    const qualified = streams.map((stream, index) => savedTwice.has(saved[index])
+        ? `${saved[index]} · ${stream.participantId ?? stream.id}`
+        : saved[index]);
+    const qualifiedTwice = repeated(qualified);
+    return new Map(streams.map((stream, index) => [
+        stream.id,
+        qualifiedTwice.has(qualified[index])
+            ? `${qualified[index]} · ${stream.id}`
+            : qualified[index],
+    ]));
+}

package/dist/run/participant-records.d.ts

@@ -28,3 +28,5 @@ export declare function eventRecordIdOf(event: RunEvent): string | undefined;
 export declare function streamParticipantIdOf(stream: Pick<RunStream, "laneId">): string | undefined;
 /** The persona recorded for a stream, including dry runs without an actor trace. */
 export declare function recordedPersonaId(bundle: Partial<Pick<RunBundle, "simulations">>, stream: Partial<Pick<RunStream, "simId">>): string | undefined;
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export declare function runParticipantCaptions(bundle: Pick<RunBundle, "streams" | "simulations">): Map<string, string>;

package/dist/run/participant-records.js

@@ -1,7 +1,9 @@
 // The run bundle's participant records, written and read. A route describes each participant (its
 // record and stream fields, its events) and these functions give them the bundle's saved shape and
-// field names; readers ask them for the ids a saved record carries. This module and run/bundle.ts
-// (its types and bundleHead) and run/streams.ts are where those contract spellings live.
+// field names; readers ask them for the ids a saved record carries and the caption it shows. This
+// module and run/bundle.ts (its types and bundleHead) and run/streams.ts are where those contract
+// spellings live.
+import { streamCaptions } from "./participant-caption.js";
 /** Ids a route chose itself, for routes whose ids are not the `sim-NNN` default. */
 export function participantIdsOf(recordId, streamId) {
     return { recordId, streamId };
@@ -67,3 +69,16 @@ export function recordedPersonaId(bundle, stream) {
         return undefined;
     return bundle.simulations.find((record) => record?.id === stream.simId)?.personaId;
 }
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export function runParticipantCaptions(bundle) {
+    return streamCaptions(bundle.streams.map((stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        const personaId = recordedPersonaId(bundle, stream);
+        return {
+            id: stream.id,
+            label: stream.label,
+            ...(participantId === undefined ? {} : { participantId }),
+            ...(personaId === undefined ? {} : { personaId }),
+        };
+    }));
+}

package/dist/run/transient-comms-secrets.d.ts

@@ -6,10 +6,11 @@ export declare function scrubTransientCommsText(text: string): string;
 /**
  * A scrub for text a model writes: each scope value as written and in its encoded forms
  * (percent-encoded, JSON-escaped, base64, base64url, hex), and where escapes split one. Text that
- * holds an encoded value is returned decoded with each value replaced. Text without one keeps its
- * original spelling, so an exact quote that holds an escape still matches its evidence. The literal
- * scrub runs first, before decoding can rewrite a value that itself holds an escape, and last,
- * because the encoded scrub leaves text inside marker-shaped spans alone. Outside a scope it
- * changes nothing.
+ * holds a value is returned decoded with each value replaced. Text without one keeps its original
+ * spelling, so an exact quote that holds an escape still matches its evidence. The literal scrub
+ * runs first, before decoding can rewrite a value that itself holds an escape, and last. The
+ * result is checked last of all: if it still holds a value as written or decoded, as a value
+ * holding part of a marker can after the literal scrub, the whole text is replaced. Outside a
+ * scope it changes nothing.
  */
 export declare function transientCommsKnownValueScrub(): (text: string) => string;

package/dist/run/transient-comms-secrets.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { decodeEscapes } from "../evidence/encoded-text.js";
-import { scrubSecretValues } from "../evidence/secret-scrub.js";
+import { REDACTION_MARKERS } from "../evidence/redaction.js";
+import { holdsSecretValue, scrubSecretValues } from "../evidence/secret-scrub.js";
 import { escapeRegExp } from "./text.js";
 const scopes = new AsyncLocalStorage();
 const MAX_VALUES = 8192;
@@ -66,39 +66,34 @@ export function scrubTransientCommsText(text) {
             .sort((a, b) => b.length - a.length)
             .map(escapeRegExp)
             .join("|"), "g");
-        return text.replace(scope.pattern, "[REDACTED_SECRET]");
+        return text.replace(scope.pattern, REDACTION_MARKERS.secret);
     }
     catch {
         return fail(scope);
     }
 }
-/**
- * The scope's values as a scrubSecretValues scrub, which also finds them percent-encoded, escaped or
- * base64-encoded and returns decoded text. Outside a scope it changes nothing.
- */
-function transientCommsEncodedScrub() {
-    const scope = scopes.getStore();
-    if (!scope)
-        return (text) => text;
-    usable(scope);
-    return scrubSecretValues([...scope.values]);
-}
-const REDACTED = "[REDACTED_SECRET]";
-const markers = (text) => text.split(REDACTED).length - 1;
+const REDACTED = REDACTION_MARKERS.secret;
 /**
  * A scrub for text a model writes: each scope value as written and in its encoded forms
  * (percent-encoded, JSON-escaped, base64, base64url, hex), and where escapes split one. Text that
- * holds an encoded value is returned decoded with each value replaced. Text without one keeps its
- * original spelling, so an exact quote that holds an escape still matches its evidence. The literal
- * scrub runs first, before decoding can rewrite a value that itself holds an escape, and last,
- * because the encoded scrub leaves text inside marker-shaped spans alone. Outside a scope it
- * changes nothing.
+ * holds a value is returned decoded with each value replaced. Text without one keeps its original
+ * spelling, so an exact quote that holds an escape still matches its evidence. The literal scrub
+ * runs first, before decoding can rewrite a value that itself holds an escape, and last. The
+ * result is checked last of all: if it still holds a value as written or decoded, as a value
+ * holding part of a marker can after the literal scrub, the whole text is replaced. Outside a
+ * scope it changes nothing.
  */
 export function transientCommsKnownValueScrub() {
-    const encoded = transientCommsEncodedScrub();
+    const scope = scopes.getStore();
+    if (!scope)
+        return scrubTransientCommsText;
+    usable(scope);
+    const values = [...scope.values];
+    const encoded = scrubSecretValues(values);
+    const holds = holdsSecretValue(values);
     return (text) => {
         const literal = scrubTransientCommsText(text);
-        const found = encoded(literal);
-        return scrubTransientCommsText(markers(found) > markers(decodeEscapes(literal)) ? found : literal);
+        const result = scrubTransientCommsText(holds(literal) ? encoded(literal) : literal);
+        return holds(result) ? REDACTED : result;
     };
 }

package/dist/study/doctor.js

@@ -368,7 +368,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ok: true,
         ...(keyed ? {} : { status: "note" }),
         message: keyed
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its estimate is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its expected cost plus a 10% margin is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }

package/dist/study/preflight-result.js

@@ -2,11 +2,12 @@
 // preflight-probes.ts both finish through these, so they live below both.
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
+import { computerUseParticipantCount } from "./routing.js";
 /** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
-    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

package/dist/study/summary.d.ts

@@ -1,4 +1,5 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
+import { type AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 export declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 export interface StudyCaps {
@@ -14,11 +15,9 @@ export interface StudySummary {
         message: string;
     };
     communications?: string;
-    analysis?: {
-        provider?: "openai" | "codex";
-        billing?: "api-estimate" | "account-unknown";
-        model: string;
-        maxCostUsd: number | null;
+    analysis?: AutomaticAnalysisBudget & {
+        /** The budget line `run` and `study check` print, from formatAutomaticAnalysisBudget. */
+        line: string;
     };
     schema: typeof STUDY_SUMMARY_SCHEMA;
     /** The study's `id`. */

package/dist/study/summary.js

@@ -12,10 +12,10 @@ import { resolveStudyDryRun } from "./plan.js";
 import { routeOf } from "./plan.js";
 import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
-import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
-import { isComputerUseComposition } from "./routing.js";
+import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { participantList, declaredParticipantCount } from "./study-fields.js";
@@ -127,7 +127,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
+    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
@@ -143,7 +143,9 @@ export async function readStudySummary(cwd, study, options = {}) {
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
-        ...(analysis ? { analysis } : {}),
+        ...(analysis
+            ? { analysis: { ...analysis, line: formatAutomaticAnalysisBudget(analysis) } }
+            : {}),
         ...(runtime
             ? { runtime: { ok: runtime.ok, installed: runtime.installed, message: runtime.message } }
             : {}),

package/dist/study/warnings.js

@@ -1,3 +1,4 @@
+import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
@@ -386,7 +387,7 @@ export function personaBackgroundWarnings(config, personas) {
             ? `persona ${personaId} has no readable background`
             : "no persona is assigned";
         return [
-            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run humanish study show ${config.id} --json to see what the participant receives.`,
+            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${config.id} --json`)} to see what the participant receives.`,
         ];
     });
 }