humanish 0.136.1 → 0.138.0

package/CHANGELOG.md

@@ -8,6 +8,29 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.138.0: A terminal study can run on Modal (2026-10-19)
+
+humanish 0.138.0 can run a terminal study's shell on Modal as well as E2B. Set
+`execution.target: modal-terminal` and `execution.runtimeAuth: openai-env`, sign in with
+`modal token new`, and install the optional `modal` package beside humanish. The sandbox runs as a
+non-root user with sudo, as on E2B, lives up to Modal's 24 hours, is journaled and reclaimed by id
+like an E2B sandbox, and is priced at Modal's sandbox rate. Desktop studies still run on E2B or a
+local VM.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.138.0)
+
+## 0.137.0: Each browser participant can record its requests (2026-10-16)
+
+humanish 0.137.0 can record the requests each hosted browser participant makes. With
+`execution.network: true`, a computer-use participant in Chrome or Chromium writes
+`network/<participant id>.ndjson`: one line per request hop with its turn, method, origin and
+path, status, duration, and whether it failed or was still open. A 500 on add-to-cart or a list
+call that never returns now sits next to the turn that started it. The file holds no headers,
+cookies, bodies or query strings, verify checks every record against the contract, and capture is
+off unless a study turns it on.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.137.0)
+
 ## 0.136.1: The emulation log no longer holds page addresses (2026-10-16)
 
 humanish 0.136.1 keeps page addresses out of a mobile-emulated participant's emulation log. The

package/dist/actors/computer-use/actor.d.ts

@@ -80,6 +80,8 @@ export interface CuaActorSessionOptions {
     onScreenshot?: (frame: Buffer) => void;
     /** Whether the trace carries the observed page, threaded to the loop; see LoopRunOptions.recordPages. */
     recordPages?: boolean;
+    /** Runtime-only checkpoint callback threaded to the loop; see LoopRunOptions.onCheckpoint. */
+    onCheckpoint?: (turnNumber: number) => void;
     /** Per-turn trace snapshot callback threaded to the loop; see CuaLoopOptions.onTrace. */
     onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }

package/dist/actors/computer-use/actor.js

@@ -58,6 +58,7 @@ export async function runCuaActorSession(options) {
         ...(options.onScreenshot === undefined ? {} : { onScreenshot: options.onScreenshot }),
         ...(options.onTrace === undefined ? {} : { onTrace: options.onTrace }),
         ...(options.recordPages === undefined ? {} : { recordPages: options.recordPages }),
+        ...(options.onCheckpoint === undefined ? {} : { onCheckpoint: options.onCheckpoint }),
     };
     const result = await runComputerUseLoopWithTaps(loopOptions);
     if (result.trace.executionProfile?.billing === "account-unknown") {

package/dist/actors/computer-use/loop/observation.js

@@ -51,6 +51,7 @@ export class DesktopObserver {
         if (frameless !== undefined)
             return { stop: frameless };
         await this.recordScreenshot(observation, opening ? "turn-00-start" : `turn-${pad(turnNumber)}`);
+        session.settings.onCheckpoint?.(turnNumber);
         session.flush();
         this.observeTasks(observation, turnNumber);
         const dwell = await this.dwellIfDue(observation, turnNumber);
@@ -58,6 +59,7 @@ export class DesktopObserver {
         if (dwell !== undefined) {
             observation = this.handToHooks(this.withHeardSpeech(await this.observeBounded("after dwell")));
             await this.recordScreenshot(observation, `turn-${pad(turnNumber)}-after-dwell`);
+            session.settings.onCheckpoint?.(turnNumber);
             this.observeTasks(observation, turnNumber);
             if (dwell.next === "stop") {
                 const when = opening ? "at the start" : `after turn ${turnNumber}`;

package/dist/actors/computer-use/loop/session.d.ts

@@ -13,7 +13,7 @@ export type ScreenshotRef = NonNullable<ActorTraceItem["screenshotRef"]>;
  * wrapped callbacks are fields on LoopSession instead. Callers destructure hooks to call them.
  */
 export type LoopSettings = {
-    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "clock" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace" | "recordPages"]: LoopRunOptions[K];
+    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "clock" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace" | "recordPages" | "onCheckpoint"]: LoopRunOptions[K];
 };
 /** The participant's dispatched actions, as the backstop and failure notices describe them. */
 export interface ActionHistory {
@@ -72,9 +72,10 @@ export declare class LoopSession {
     /** Set by the participant's own final account or by its closing report. */
     impressions: ParticipantImpressions | undefined;
     private stopCause;
-    private readonly scrubText;
+    private readonly redactTrace;
     constructor(options: LoopRunOptions);
     remaining(): number;
+    /** Model-authored narration and recorded pages, through traceRedaction. */
     redactNarration(text: string): string;
     /** Hand a watcher the trace so far with the running usage, without waiting on it. */
     flush(): void;

package/dist/actors/computer-use/loop/session.js

@@ -1,4 +1,4 @@
-import { redactEncodedText } from "../../../evidence/encoded-text.js";
+import { traceRedaction } from "../../../evidence/trace-page.js";
 import { TaskTracker } from "../../../study/tasks.js";
 import { StreakRecord } from "./streak.js";
 import { TraceRecorder } from "./trace.js";
@@ -73,10 +73,10 @@ export class LoopSession {
     /** Set by the participant's own final account or by its closing report. */
     impressions;
     stopCause;
-    scrubText;
+    redactTrace;
     constructor(options) {
         // Read once, in this order: a caller mutating its options object mid-run changes nothing.
-        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, clock, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, recordPages, } = options;
+        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, clock, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, recordPages, onCheckpoint, } = options;
         this.settings = {
             instructions,
             persona,
@@ -93,6 +93,7 @@ export class LoopSession {
             onScreenshot,
             onTrace,
             recordPages,
+            onCheckpoint,
         };
         this.provider = provider;
         this.executor = executor;
@@ -108,7 +109,8 @@ export class LoopSession {
         this.redactScreenshots = redactScreenshots;
         this.now = () => now();
         this.acknowledgeSafetyChecks = (checks) => acknowledgeSafetyChecks(checks);
-        this.scrubText = (text) => scrubText(text);
+        // The run's scrubKnownValues comes in as scrubText.
+        this.redactTrace = traceRedaction((text) => scrubText(text), (text) => redaction.redactText(text));
         this.writeScreenshot = (name, bytes) => writeScreenshot(name, bytes);
         this.sleep = (ms) => sleep(ms);
         this.capDeclared = maxUsd !== undefined || overRunBudget !== undefined;
@@ -123,15 +125,9 @@ export class LoopSession {
     remaining() {
         return this.timeoutMs - (this.now() - this.startedAtMs);
     }
-    // Model-authored narration: literal-scrub known provisioned values, then pattern-redact.
-    // A value the model transcribes (a DB password it read on screen) has no shape, so redactText
-    // alone cannot catch it; the run's scrubKnownValues, injected as scrubText, closes that. The
-    // participant receives its instructions as written, so it can repeat a key the study wrote
-    // base64- or percent-encoded, which verify decodes; redactEncodedText removes that one too.
-    // The known values are scrubbed again last: a marker written before other text can spell one,
-    // as `[REDACTED_SECRET] and` spells `SECRET] and`.
+    /** Model-authored narration and recorded pages, through traceRedaction. */
     redactNarration(text) {
-        return this.scrubText(redactEncodedText(this.settings.redaction.redactText(this.scrubText(text))));
+        return this.redactTrace(text);
     }
     /** Hand a watcher the trace so far with the running usage, without waiting on it. */
     flush() {

package/dist/actors/computer-use/loop/types.d.ts

@@ -484,7 +484,10 @@ export interface LoopTaps {
      */
     onScreenshot?: (frame: Buffer) => void;
 }
-/** The loop's options inside humanish: the public ones, the handoff's taps and the page switch. */
+/**
+ * The loop's options inside humanish: the public ones, the handoff's taps, the page switch and the
+ * checkpoint tap.
+ */
 export type LoopRunOptions = CuaLoopOptions & LoopTaps & {
     /**
      * Whether screenshot items and the trace carry the observed page (`page`, `finalPage`).
@@ -492,6 +495,16 @@ export type LoopRunOptions = CuaLoopOptions & LoopTaps & {
      * as digests (docs/architecture/external-public-shared-world.md).
      */
     recordPages?: boolean;
+    /**
+     * Runtime-only checkpoint tap: called with the turn's number after its checkpoint screenshot
+     * item (turn-03) is recorded, and again after its after-dwell item (turn-03-after-dwell),
+     * before the turn's stop checks. A held turn and a reply cut off by the output limit take no
+     * checkpoint, so they never reach it. Default: no-op.
+     *
+     * Built-in caller: the hosted E2B desktop pairs the number with the time of the browser-state
+     * read that screenshot came after, and its network log numbers requests by those pairs.
+     */
+    onCheckpoint?: (turnNumber: number) => void;
 };
 export type CuaLiveMetadata = Pick<ActorTrace, "executionProfile" | "providerRequests" | "historyTurnsOmitted">;
 /** What runComputerUseLoop returns; the public name for an actor session result. */

package/dist/cli/commands/runs.js

@@ -203,12 +203,12 @@ export function registerRuntimeCommands(parent, io) {
 export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
-        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox E2B lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks E2B whether each still exists and kills nothing. Needs E2B_API_KEY in the environment or in --dotenv.")
+        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox the run's provider lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks the provider whether each still exists and kills nothing. Needs E2B_API_KEY, or MODAL_TOKEN_ID and MODAL_TOKEN_SECRET for a run on Modal, in the environment or in --dotenv.")
         .summary("Stop or check an interrupted run's sandboxes.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
-        .option("--check", "Ask E2B whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
+        .option("--check", "Ask the provider whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
         .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
         .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)

package/dist/cli/doctor.js

@@ -96,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
     const checks = [
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
+        ...(setup?.keys.includes("MODAL_TOKEN_ID") === true ? [await modalSdkCheck()] : []),
         sandboxCeilingCheck(env),
         concurrentSandboxesCheck(env),
         terminalSurfaceCheck(),
@@ -239,6 +240,25 @@ async function desktopSdkCheck(setup) {
                 : missingDesktopSdkMessage(humanishInstall()),
     };
 }
+/** The optional `modal` peer, reported only for a study that runs on Modal, which needs it. */
+async function modalSdkCheck() {
+    const present = await safeCheck(async () => {
+        try {
+            await import("modal");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return {
+        name: "modal sdk",
+        ok: present,
+        message: present
+            ? "optional peer modal is installed; provider access is not tested"
+            : `optional peer modal is absent, and this study runs on Modal. ${desktopPeerAdvice(humanishInstall(), "modal").advice}`,
+    };
+}
 /**
  * The stakeholder surface. Reported as capability, never as a gate: the TUI is optional,
  * and `doctor` is itself mostly run by agents through a pipe, where a TTY requirement says
@@ -288,6 +308,10 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     if (study) {
         const { resolveStudyManifest } = await import("../study/discover.js");
         const resolved = await resolveStudyManifest(cwd, study);
+        // A study on Modal reads the Modal token pair, which no other study needs.
+        if (resolved.ok && resolved.config.execution?.target === "modal-terminal")
+            for (const name of ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"])
+                keyNames.add(name);
         if (resolved.ok && resolved.config.comms?.email?.kind === "real") {
             const { receivingRequiredKey } = await import("../comms/setup.js");
             receivingKey = await receivingRequiredKey(cwd, resolved.config.comms.email.connection);

package/dist/evidence/browser-network.d.ts

@@ -0,0 +1,108 @@
+export declare const BROWSER_NETWORK_SCHEMA = "humanish.browser-network.v1";
+/** Why records are missing from a participant's network log, as the index's `reason` says. */
+export declare const BROWSER_NETWORK_GAPS: readonly ["no-capture", "holder-stopped", "capped", "not-collected"];
+type BrowserNetworkGap = (typeof BROWSER_NETWORK_GAPS)[number];
+/** A stream's `network` field in run.json. */
+export interface BrowserNetworkIndex {
+    schema: typeof BROWSER_NETWORK_SCHEMA;
+    /**
+     * network/<participant id>.ndjson, with the file's record count, byte count and sha256, and how
+     * many of its records failed and are pending. All six are absent when no file was written:
+     * capture did not start (`no-capture`), the events were not read (`not-collected`), or capture
+     * started and kept no record, which `startedAt` tells apart.
+     */
+    path?: string;
+    records?: number;
+    /** Records with `failed`: requests that got no response or broke off. */
+    failed?: number;
+    /**
+     * Records with `pending`: requests with no recorded end, still open when the file was read or
+     * when capture stopped (`capped`, `holder-stopped`).
+     */
+    pending?: number;
+    bytes?: number;
+    sha256?: string;
+    /** When the launch page's Network domain answered, on the desktop's clock. */
+    startedAt?: string;
+    /** The origins whose requests are written, redacted as a trace page's origin is. */
+    origins: string[];
+    complete: boolean;
+    /** Present when `complete` is false. */
+    reason?: BrowserNetworkGap;
+    omitted: {
+        /** Requests to an origin outside `origins`. */
+        otherOrigin: number;
+        /**
+         * Records past the writer's caps, which are not checked. Requests after the holder's own cap
+         * (`capped` with no overCap) are not counted anywhere.
+         */
+        overCap: number;
+        /** Records that failed the record check. */
+        invalid: number;
+    };
+}
+/**
+ * A checkpoint screenshot's browser-state read: `wallTime` is the read's clock in seconds since the
+ * epoch on the desktop, the clock the holder's request times use, and `turn` the screenshot's N.
+ */
+export interface TurnMark {
+    wallTime: number;
+    turn: number;
+}
+export interface BrowserNetworkCapture {
+    /** The participant's id, which names the file. */
+    participantId: string;
+    /** The origins whose requests are kept, as `new URL(url).origin` writes them. */
+    origins: readonly string[];
+    /** The holder's events file as the host read it, whole lines and possibly a last partial one. */
+    events: string;
+    /** The participant's checkpoint marks, in the order they were taken. */
+    marks: readonly TurnMark[];
+    /** The trace redaction the participant's pages went through (traceRedaction). */
+    redact: (text: string) => string;
+    /**
+     * The holder had exited before `events` was read. A holder killed by a signal writes no exit
+     * line, so without this the file reads as complete.
+     */
+    holderExited?: boolean;
+    /**
+     * The participant's own sandbox id and those the run journaled. Run.finish rewrites a journaled
+     * id in every run file after run.json indexes them, so the writer withholds each path segment
+     * that names one, before any cut, and the sweep finds nothing to change.
+     */
+    sandboxIds?: readonly string[];
+}
+export interface BrowserNetworkLog {
+    index: BrowserNetworkIndex;
+    /** The file's text, for `index.path`; absent when the index has no path. */
+    text?: string;
+    /** What a reader of the run should know about the log, such as records with no turn. */
+    warnings: string[];
+}
+/** Whether `value` is an ISO time as `Date.prototype.toISOString` writes one. */
+export declare function isIsoTime(value: unknown): value is string;
+/** The run-relative path of a participant's network log. */
+export declare function networkLogPath(participantId: string): string;
+/**
+ * What is wrong with one network log record, or undefined when it holds only the schema's keys and
+ * values. The writer leaves out a record this names; verify reports one as a finding. Never says
+ * what the record holds.
+ */
+export declare function networkRecordProblem(record: unknown): string | undefined;
+/**
+ * The index of a participant whose events were never read: capture did not start, or the file
+ * could not be read at teardown. No file goes with it.
+ */
+export declare function networkIndexWithoutEvents(capture: Pick<BrowserNetworkCapture, "origins" | "redact" | "sandboxIds">, reason: "no-capture" | "not-collected"): BrowserNetworkIndex;
+/**
+ * The network log of one participant: the records the holder's events give, joined by request id
+ * into one per hop, redacted, tagged with turns, checked and capped, then the index that binds
+ * them. A redirect gives the 3xx hop's record, then one with `redirect: true`. A request's turn is
+ * the N of the first mark at or after its start, or the last mark's N plus 1 after every mark.
+ * Capture that started and kept no record writes no file. Only a hop the caps still take is
+ * redacted, and the work yields to the event loop every 20 ms, so the other participants of a
+ * fan-out keep running while a 32 MiB events file is reduced. Throws only for a participant id
+ * that is not one path segment.
+ */
+export declare function reduceBrowserNetwork(capture: BrowserNetworkCapture): Promise<BrowserNetworkLog>;
+export {};