humanish 0.131.1 → 0.133.0

package/dist/evidence/sensitive-json.js

@@ -0,0 +1,96 @@
+// containsSensitive over a JSON document that may not fit in one string. V8's longest string is
+// 536,870,888 characters on Node 24, and a run with every participant's trace loaded can pass it.
+//
+// The document is scanned as pieces: the text before the array and its first element, each
+// element after that, and the last element with the text after the array. Every cut then falls on
+// the `,` between two objects, `},{`. Most patterns stop at a quote, so a match stays inside one
+// JSON string. Those that read a name and its value cross only the quotes around its `:`. A
+// credential variable's unquoted value runs over brackets and braces up to a comma, so at a cut it
+// stops, but after the last element it can run over the array's `]`. That is why the text after
+// the array joins the last element.
+//
+// The sandbox URL can cross a cut. Its user info runs over quotes, braces and commas up to an `@`:
+// `https://host"},{"contact":"ops@e2b-host`. From the end of its scheme to one character past
+// `e2b`, that match holds no slash and no whitespace. So a match across a cut starts at a scheme
+// with no slash or whitespace after it up to the cut, and reaches the next piece only up to its
+// first slash or whitespace. Between that scheme and the cut, the match can only be in its user
+// info. The scheme and every `@` there are inside JSON strings, so a host that starts after one
+// stops at its string's closing quote. Had that host reached `e2b` first, the scan of its piece or
+// an earlier junction would have matched. So the scan keeps only the scheme between pieces. Each
+// cut's junction scans the scheme, `"}` in place of the text after it, the cut's `,` and the next
+// piece up to its first slash or whitespace. A public E2B page after the scheme would need a space
+// or the text's end before the cut, so neither text exempts the URL. The scan holds one piece at a
+// time.
+import { isRecord } from "../run/type-guards.js";
+import { containsSandboxUrl, containsSensitive } from "./redaction.js";
+// The sandbox URL's scheme, `https://` or `https:\/\/` as JSON may escape it, at a text's end.
+const SCHEME_AT_END = /https?:\\?\/\\?\/$/i;
+const SLASH_OR_SPACE = /[/\s]/;
+/**
+ * containsSensitive(JSON.stringify(value)), with each element of the array `value[key]` serialized
+ * and scanned on its own, so no one string holds two elements. Only an array of plain objects is
+ * scanned that way. Any other array, and a value, array or element with a toJSON or a prototype of
+ * its own, is scanned as the whole text, which can be longer than one string holds. Getters and
+ * proxies are not detected, so the answer is the whole text's for values as JSON.parse returns
+ * them.
+ */
+export function containsSensitiveJson(value, key) {
+    // JSON.stringify writes only own enumerable keys, and `around` cuts the text at this one.
+    const elements = isPlainRecord(value) && Object.keys(value).includes(key) ? value[key] : undefined;
+    // Array.from reads a hole as undefined, where every would skip it.
+    if (!isPlainRecord(value) ||
+        !isPlainArray(elements) ||
+        !Array.from(elements).every(isPlainRecord))
+        return wholeTextSensitive(value);
+    const [prefix, suffix] = around(value, key);
+    if (elements.length === 0)
+        return containsSensitive(prefix + suffix);
+    // The scheme of a URL no slash or whitespace has followed, from an earlier piece.
+    let scheme;
+    for (const [index, element] of elements.entries()) {
+        const own = JSON.stringify(element);
+        const piece = (index === 0 ? prefix : "") + own + (index === elements.length - 1 ? suffix : "");
+        if (containsSensitive(piece))
+            return true;
+        if (scheme !== undefined && containsSandboxUrl(`${scheme}"},${head(piece)}`))
+            return true;
+        scheme = schemeAfter(scheme, piece);
+    }
+    return false;
+}
+const wholeTextSensitive = (value) => containsSensitive(JSON.stringify(value) ?? "");
+// JSON.stringify calls a toJSON with the value's key in its parent, and an element serialized
+// alone gets "" in place of its index. It writes a boxed primitive as the primitive. A plain object
+// or array with no toJSON is written as its own keys or items wherever it sits.
+const hasToJson = (value) => typeof value.toJSON === "function";
+function isPlainRecord(value) {
+    if (!isRecord(value) || hasToJson(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const isPlainArray = (value) => Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype && !hasToJson(value);
+/** The document's text before the first element of `value[key]` and after its last. */
+function around(value, key) {
+    const keys = Object.keys(value);
+    const at = keys.indexOf(key);
+    const entries = (from, to) => Object.fromEntries(keys.slice(from, to).map((name) => [name, value[name]]));
+    const before = JSON.stringify({ ...entries(0, at), [key]: [] });
+    const after = JSON.stringify(entries(at + 1));
+    return [before.slice(0, -"]}".length), after === "{}" ? "]}" : `],${after.slice(1)}`];
+}
+/** `piece` up to and including its first slash or whitespace, or all of it when it has none. */
+function head(piece) {
+    const at = piece.search(SLASH_OR_SPACE);
+    return at === -1 ? piece : piece.slice(0, at + 1);
+}
+/** The scheme a sandbox URL could continue from after `piece`, given the one before it. */
+function schemeAfter(before, piece) {
+    let last = piece.length - 1;
+    while (last >= 0 && !SLASH_OR_SPACE.test(piece[last]))
+        last -= 1;
+    if (last === -1)
+        return before;
+    // `https:\/\/` is the longest scheme: ten characters ending at the slash.
+    return SCHEME_AT_END.exec(piece.slice(Math.max(0, last - 9), last + 1))?.[0];
+}

package/dist/routes/computer-use/local-vm.js

@@ -1,5 +1,6 @@
 import { collectDesktopRecording } from "../../evidence/desktop-recording-artifact.js";
 import path from "node:path";
+import { participantList } from "../../study/study-fields.js";
 import { inboxRecipientFor, } from "./participant-desktop.js";
 import { createLocalFirecrackerDesktop, } from "../../substrates/local/firecracker-desktop.js";
 import { localBrowserDefaults, localBrowserUnsupportedReason, } from "../../substrates/local/runtime-config.js";
@@ -139,11 +140,16 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
     };
 }
 /** The Codex account participant, whose unconfirmed cleanup blocks the study's analysis. */
-function accountProvider(state, maxWaitMs) {
-    return async ({ executor }) => {
+function accountProvider(state, config) {
+    return async ({ executor, participant: { index } }) => {
+        // The wait settings the participant's loop runs with (plan-participants.ts), so its tool
+        // description states them.
+        const maxWaitMs = config.actor?.maxWaitMs;
+        const idleWaitMs = participantList(config)?.[index]?.idleWaitMs ?? config.actor?.idleWaitMs;
         const participant = createRestrictedCodexParticipant({
             speechEnabled: executor.speechEnabled === true,
             ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
+            ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
         });
         state.participants.push(participant);
         const provider = Object.assign(participant.provider, {
@@ -185,7 +191,7 @@ export function prepareLocalVmRun(options) {
     const { config: _config, assets: _assets, signal: _signal, ...runOptions } = options;
     return {
         options: account
-            ? { ...runOptions, createProvider: accountProvider(state, config.actor?.maxWaitMs) }
+            ? { ...runOptions, createProvider: accountProvider(state, config) }
             : runOptions,
         localVm: {
             desktop: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),

package/dist/routes/computer-use/participant-model.js

@@ -47,6 +47,9 @@ export async function startParticipantModel(spec, deps, executor) {
             ...(spec.planned.limits.maxWaitMs === undefined
                 ? {}
                 : { maxWaitMs: spec.planned.limits.maxWaitMs }),
+            ...(spec.planned.limits.idleWaitMs === undefined
+                ? {}
+                : { idleWaitMs: spec.planned.limits.idleWaitMs }),
             session: { env },
         });
         return { provider: codexParticipant.provider, codexParticipant };

package/dist/study/bundle-estimate.d.ts

@@ -16,6 +16,11 @@ export interface BundleEstimate {
     readonly runFileBytes: number;
     /** The largest participant trace file, which analysis also reads whole. */
     readonly largestTraceBytes: number;
+    /**
+     * Every participant's trace file together, whose items the run writer and the Observer page join
+     * in one string.
+     */
+    readonly tracesBytes: number;
     /** observer/index.html, which verify reads whole. */
     readonly observerPageBytes: number;
     /** Every file, screenshots included. */

package/dist/study/bundle-estimate.js

@@ -16,6 +16,13 @@
 // observer-data.json leaves the lists out too and was 0.94 to 1.12 of run.json's size on the live
 // runs measured, so it passes 32 MiB only after run.json passes 16 MiB, and the estimate does not
 // check it.
+// The Observer page and the Observer server join every participant's items in one string before
+// gzip. On a hosted desktop the sandbox id scrub (publicSandboxView) does too, on every write of
+// run.json and on a bundle export of the loaded run, which its 25 MiB default --max-bytes refuses
+// first. V8's longest string is 536,870,888 characters
+// on Node 24. A trace file's bytes are at least the characters of its items as compact JSON, so the
+// estimate compares the traces' bytes and may warn a little early.
+import { constants } from "node:buffer";
 import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
 import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { formatDuration } from "../run/projection.js";
@@ -156,6 +163,7 @@ export function estimateBundle(participants, sessionMs) {
     return {
         runFileBytes,
         largestTraceBytes: largestTrace,
+        tracesBytes: traces,
         observerPageBytes,
         // observer-data.json is about run.json's size.
         totalBytes: observerPageBytes + screenshots * RATES.screenshotBytes + traces + 2 * runFileBytes,
@@ -178,6 +186,7 @@ export function estimateBundle(participants, sessionMs) {
 export function bundleLimitReason(estimate) {
     const runFile = estimate.runFileBytes > EVIDENCE_LIMITS.sourceBytes;
     const page = estimate.observerPageBytes > RUN_ARTIFACT_MAX_BYTES;
+    const joined = estimate.tracesBytes > constants.MAX_STRING_LENGTH;
     const entries = estimate.entries > estimate.entryLimit;
     const passed = [
         ...(runFile
@@ -195,6 +204,11 @@ export function bundleLimitReason(estimate) {
                 `The Observer page, observer/index.html, may grow to about ${mib(estimate.observerPageBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads in one file.`,
             ]
             : []),
+        ...(joined
+            ? [
+                `All participants' traces together may grow to about ${mib(estimate.tracesBytes)}, past the ${mib(constants.MAX_STRING_LENGTH)} that fits in one string. On a hosted desktop, writing run.json puts them in one string, and so does a bundle export allowed past its 25 MiB default; the Observer page always does. run.json may then stop updating, that export would fail and the page would not build.`,
+            ]
+            : []),
         ...(entries
             ? [
                 `The run may hold about ${count(estimate.entries)} files and folders, past the ${count(estimate.entryLimit)} the public-safety scan reads in a run of ${plural(estimate.basis.participants, "participant")}.`,
@@ -222,7 +236,7 @@ export function bundleLimitReason(estimate) {
         ...(runFile ? ["shorten the mission (actor.mission)"] : []),
     ];
     // A trace is one participant's, so splitting the study helps only the run's own files.
-    if (runFile || page || entries || changes.length === 0)
+    if (runFile || page || joined || entries || changes.length === 0)
         changes.push("split the participants across studies");
     const advice = changes.length < 2
         ? changes.join("")

package/dist/study/types.d.ts

@@ -414,10 +414,11 @@ export interface StudyActor {
     maxWaitMs?: number;
     /**
      * Computer-use and shared-world: how long a `wait` that names no duration lasts when the
-     * participant's turn only waits or takes screenshots, and how often the loop looks at the screen
-     * while it watches such a turn, in whole milliseconds from 1000 to 600000 and no longer than
-     * maxWaitMs. Default 5000. After an action in the same turn such a wait lasts 500 ms. OpenAI's
-     * computer-use `wait` never names a duration.
+     * participant's turn only waits or takes screenshots, the shortest such a turn is watched for,
+     * and how often the loop looks at the screen while it watches such a turn, in whole milliseconds
+     * from 1000 to 600000 and no longer than maxWaitMs. Default 5000. After an action in the same
+     * turn such a wait lasts 500 ms. OpenAI's computer tool `wait` never names a duration; its
+     * wait_minutes function does.
      */
     idleWaitMs?: number;
     /**

package/dist/verify/verify.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { listAnalysisExecutions } from "../analysis/store-executions.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
-import { containsSensitive, REDACTED_SANDBOX_ID } from "../evidence/redaction.js";
+import { REDACTED_SANDBOX_ID } from "../evidence/redaction.js";
+import { containsSensitiveJson } from "../evidence/sensitive-json.js";
 import { keyedSandboxIds, readRunSandboxIds } from "../run/sandbox-ids.js";
 import { validatePreparedRunArtifactPaths } from "../run/paths.js";
 import { isReadRunBundleSchema, RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, RUN_BUNDLE_V2_SCHEMA, RUN_BUNDLE_V3_SCHEMA, } from "../run/bundle.js";
@@ -112,9 +113,10 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     addTraceScan(traces, publicSafetyFindings, unscannedArtifacts);
     // JSON escapes can hide a sensitive value from the byte scan while the
     // decoded recording exposes it to Observer, feedback, or analysis input.
+    // Each participant is scanned apart: together their traces can pass V8's longest string.
     if (publicSafetyFindings.length < MAX_REPORTED_FINDINGS &&
         recorded !== null &&
-        containsSensitive(JSON.stringify(recorded))) {
+        containsSensitiveJson(recorded, "streams")) {
         publicSafetyFindings.push("sensitive decoded run.json");
     }
     checks.push({

package/docs/architecture/actor-contract.md

@@ -176,6 +176,7 @@ export interface ActorTraceItem {
     looks: number;
     area?: { x: number; y: number; width: number; height: number }; // pixels, coordinates only
   };
+  namedMs?: number; // computer-use wait ui_action: the length the participant named, before any cap
 }
 
 export interface ActorCapabilities {
@@ -387,9 +388,14 @@ request), without provider support, or without remaining time and known budget.
 unreported usage remains an unknown cost line. `counts.debriefCalls` is separate
 from interaction turns, and reported usage contributes to aggregate cost.
 
-The OpenAI implementation makes one request with tools disabled and structured
-output; no HTTP or policy retries. Its output limit is 3072 tokens, or the declared
-`maxOutputTokens` when lower. Stateless/ZDR mode does not offer retrospective
+The OpenAI implementation sends each closing request with tools disabled and no HTTP or
+policy retries. The request sends no `text.format`, so it reads the session from the prompt
+cache, and states the JSON Schema in its input. The reply's JSON object is read from its text,
+also from inside a code fence or after a message of its own. A completed reply with no JSON that
+schema accepts, apart from a refusal, comes back with `closingRetry` set. The loop may then call
+the same method once more, after the checks the first request passed and with a time bound of
+its own, and that request sets the strict schema. `counts.debriefCalls` counts each request. Its
+output limit is 3072 tokens, or the declared `maxOutputTokens` when lower. Stateless/ZDR mode does not offer retrospective
 reporting: its client-carried conversation summarizes its oldest turns past a token
 budget, so it may not hold the whole session a retrospective report needs. It does offer
 the impressions-only request, which reads the carried conversation: its newest

package/docs/architecture/browser-control.md

@@ -110,8 +110,8 @@ with speech, whose heard speech reaches the participant only with a screenshot),
 shortened` notice with both durations when it does, and sends the rest as consecutive waits of at
 most 30 seconds. The Codex participant's `humanish_ui` schema leaves a wait's length open for that
 reason; the wire still refuses a single wait over 30 seconds. A wait that names no duration, as
-every OpenAI computer-use wait does, reaches the desktop with a length too: 500 ms after an action
-in the same turn. A turn that only waits or takes screenshots sends no wait to the desktop: the
+the OpenAI computer tool's `wait` does, reaches the desktop with a length too: 500 ms after an
+action in the same turn. A turn that only waits or takes screenshots sends no wait to the desktop: the
 loop observes the screen every `actor.idleWaitMs` until it changes or the wait's time passes
 (`src/actors/computer-use/loop/watch.ts`), so a waiting participant costs one observe request per
 look.

package/docs/contracts/schemas.md

@@ -1082,14 +1082,17 @@ Core-owned fields:
   16 pixels counts once it holds still at a look; one of 24 tiles or fewer once
   it has held still for more than 65 s with no tile within 4 tiles of it ticking
   or moving with a region of more than 24 tiles
-  (`src/evidence/frame-change.ts`). The first watch lasts the turn's planned
-  length: the named waits' lengths, together up to `actor.maxWaitMs` (else
-  600000), and `idleWaitMs` for each wait that names none. Each further one in a row that ended
-  at its limit, or that a change of 24 tiles or fewer woke, lasts twice as long,
-  up to the larger of its planned length and that cap. `limitMs` is how long it
-  could last; `askedMs` is what the turn's waits asked for, the same sum with no
-  cap, so it is above `limitMs` when the named waits passed the cap and below it
-  when the watch grew; `wake` is `changed`, `speech`,
+  (`src/evidence/frame-change.ts`). The first watch's limit is the turn's
+  planned length: the named waits' lengths, together up to `actor.maxWaitMs` (else
+  600000), and `idleWaitMs` for each wait that names none, and at least
+  `idleWaitMs`. Each further one in a row that ended at its limit, or that a
+  change of 24 tiles or fewer woke, lasts twice as long, up to the larger of its
+  planned length and that cap. An OpenAI participant names a length with the
+  `wait_minutes` function tool; its computer tool's `wait` names none.
+  `limitMs` is how long it could last; `askedMs` is what the turn's
+  waits asked for, the same sum with no cap, so it is above `limitMs` when the
+  named waits passed the cap and below it when the watch grew or the named waits
+  were shorter than `idleWaitMs`; `wake` is `changed`, `speech`,
   `condition`, `limit`, `clock` (wind-down or end), `stalled` (a look got no
   frame; the next observation is a fresh one), or `stopped` (the study budget or
   the session's time ran out); `looks` counts its looks; `area` (`x`, `y`,
@@ -1100,6 +1103,14 @@ Core-owned fields:
   waits after the one carrying `watch` are titled `wait 0ms`. The look that
   ended a watch is the turn's `turn-NN` screenshot; other looks are not kept.
   Additive: absent on plain waits, other producers and older bundles
+- optional `items[].namedMs`, on the computer-use `ui_action` of each wait that
+  named its length: that length in milliseconds, as the participant named it,
+  before `actor.maxWaitMs` or the watch's cap applied. An OpenAI participant
+  names a length only through `wait_minutes`, so its waits with `namedMs` are
+  that tool's calls. Its waits without it are the computer tool's `wait`, a
+  `wait_minutes` call whose minutes were not a finite number above zero, and
+  a call to a function it does not have. Additive: absent on waits that named
+  none, other items and producers, and older bundles
 - optional `items[].page` and `finalPage` (`{ origin, path }`, `TracePage` in
   `src/actors/contract.ts`): where a computer-use participant's browser was. The loop puts `page`
   on the `screenshot` item of each observation that read a URL: `turn-00-start` is the page before
@@ -1183,8 +1194,9 @@ Core-owned fields:
   with the outputs that answered it, and the latest reply. Past an estimated
   64,000 input tokens it is cut down to 32,000 in one step: the opening
   screenshot is dropped first, then the oldest exchanges become lines of a note,
-  sent as an assistant message, that keeps their reasoning summaries, messages
-  and actions as text, with any text that came back with their screenshots.
+  sent as an assistant message, that keeps their reasoning summaries, messages,
+  actions and `wait_minutes` calls as text, with any text that came back with
+  their screenshots or in a function call's output, such as how a wait ended.
   Past 32,000 characters the note keeps its first four lines and its newest
   ones, and names the turns between them as not listed.
   The two newest exchanges are always carried whole, even when they alone pass
@@ -1199,7 +1211,14 @@ Core-owned fields:
   `estimatedInputTokens`. The impressions-only request has `kind: impressions`;
   the optional `kind` field is absent on participant turns and in older bundles.
   Impressions carry the context the next turn would carry, with the same budget
-  and summarization of older turns. Billed input per request is in `tokenUsage.turns`. A
+  and summarization of older turns. The closing report and impressions requests
+  send no `text.format`, so they can read the session from the prompt cache; the
+  request states the JSON Schema in its input instead. A completed reply with no
+  JSON the schema accepts, apart from a refusal, can be sent once more with the
+  strict schema, only after the budget and time checks the first passed and with
+  a time bound of its own. An impressions request sent twice has two entries. The
+  closing report has no entry here. Each closing request that reported usage has
+  its own row in `tokenUsage.turns` after the participant's requests. Billed input per request is in `tokenUsage.turns`. A
   participant that ran in `explicit_context` gets a run warning. Absent on other
   providers and on earlier bundles
 - optional `affordanceUse` (`humanish.affordance-use.v1`): which kind of route this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.131.1",
+  "version": "0.133.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",