humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,222 @@
+// The model side of one computer-use lane: the provider a local agent brings, the session options
+// the loop runs with, the study's shared spend ledger, the provider cleanup, and the checks on the
+// finished session. The desktop side stays with the lane runner.
+import { startClaudeSession } from "../../actors/local-agent/claude-session.js";
+import { createLocalAgentProvider } from "../../actors/local-agent/cli.js";
+import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provider.js";
+import { estimateActorCostForExecution, round6 } from "../../run/pricing.js";
+import { redactText } from "../../evidence/redaction.js";
+import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
+import { writeContainedOutputFile } from "../../run/contained-output.js";
+import { withInboxMission } from "./participant-prompt.js";
+import { resolveSelfReportedBlocker, resolveSelfReportedFriction, sessionEnding, } from "./self-report.js";
+import { hollowCompletion } from "../../run/judge.js";
+import { legacyHookSpecOf } from "./legacy-lane-spec.js";
+/** Starts the lane's model: a caller's provider, the operator's Codex, a Claude session, or none. */
+export async function startParticipantModel(spec, deps, executor) {
+    const { config, env } = deps;
+    if (deps.hooks.buildProvider) {
+        return {
+            provider: await deps.hooks.buildProvider({
+                config,
+                actor: deps.descriptor,
+                lane: legacyHookSpecOf(spec),
+                laneCount: deps.participantCount,
+                executor,
+            }),
+        };
+    }
+    if (deps.localAgent === "codex") {
+        // Hosted local-agent studies use the same native participant engine as local desktops.
+        // Operator auth deliberately retains the operator's Codex home, config and supported auth
+        // stores instead of applying the isolated restricted-account profile used by local studies.
+        const codexParticipant = createRestrictedCodexParticipant({
+            authMode: "operator",
+            ...(spec.planned.limits.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+            ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+            ...(executor.speechEnabled === true ? { speechEnabled: true } : {}),
+            session: { env },
+        });
+        return { provider: codexParticipant.provider, codexParticipant };
+    }
+    if (deps.localAgent === "claude") {
+        // One session for the whole run, like the codex thread above (#520). The one-shot
+        // provider (createLocalAgentProvider) spawned `claude -p` per turn, and every turn
+        // started with no memory of the last. HUMANISH_LOCAL_AGENT_ONE_SHOT=1 keeps that path
+        // reachable as a MEASUREMENT switch: MemTrapBench (2026-08) reports memory frameworks
+        // degrading agent performance by 10-40% on some tasks, so "remembers" has to be measured
+        // against "does not" on the same lab, not assumed. The trace records which one ran.
+        const oneShot = env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== undefined &&
+            env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== "" &&
+            env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== "0";
+        if (oneShot) {
+            return {
+                provider: createLocalAgentProvider({
+                    agent: "claude",
+                    ...(spec.planned.limits.reasoningEffort === undefined
+                        ? {}
+                        : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+                    ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+                }),
+            };
+        }
+        const claudeSession = await startClaudeSession({
+            ...(spec.planned.limits.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+            ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+        });
+        return { provider: claudeSession.provider, claudeSession };
+    }
+    return {};
+}
+/** The options the lane's session runs with: prompt, model settings, spend caps and callbacks. */
+export function participantSessionOptions(spec, deps, ready, provider, writeScreenshot) {
+    const { config } = deps;
+    const { executor, inbox } = ready;
+    // The FAIL-CLOSED spend cap (execution.caps.maxUsd) is wired into the loop as maxUsd + an
+    // injected pure per-turn estimator keyed on the resolved model. Preflight already refused a
+    // cap on an unpriced model, so the estimate is measurable whenever a cap is in force. The
+    // model id here matches provider.version (openai-responses-cu resolves the default when unset).
+    const capModelId = config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL;
+    const maxUsd = config.execution?.caps?.maxUsd;
+    return {
+        instructions: inbox
+            ? withInboxMission(spec, inbox.url, inbox.address, inbox.receiving).instructions
+            : spec.instructions,
+        persona: spec.persona,
+        timeoutMs: deps.timeoutMs,
+        // The brain is either a keyed API client or a CLI the operator is already signed in to.
+        // Everything below this line — loop, executor, trace, affordances — is identical either
+        // way, which is what makes a local-agent run comparable to an API one.
+        ...(provider === undefined ? {} : { provider: provider }),
+        openai: {
+            apiKey: deps.openaiApiKey,
+            ...(config.actors[0]?.model ? { model: config.actors[0].model } : {}),
+            // Per-LANE, not per-actor: two lanes at different efforts is the control this exists for.
+            ...(spec.planned.limits.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+            ...(spec.planned.limits.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: spec.planned.limits.maxOutputTokens }),
+        },
+        ...(maxUsd === undefined
+            ? {}
+            : {
+                maxUsd,
+                estimateTurnCostUsd: (usage) => estimateActorCostForExecution(usage, provider?.version ?? capModelId, provider?.executionProfile).estimatedCostUsd,
+            }),
+        executor,
+        redactScreenshots: deps.redactScreenshots,
+        scrubText: deps.scrubKnownValues,
+        writeScreenshot,
+        ...(spec.backstop?.idleSteps === undefined ? {} : { idleSteps: spec.backstop.idleSteps }),
+        ...(spec.backstop?.noProgressSteps === undefined
+            ? {}
+            : { noProgressSteps: spec.backstop.noProgressSteps }),
+        ...(spec.planned.limits.stopWhen === undefined
+            ? {}
+            : { stopWhen: spec.planned.limits.stopWhen }),
+        ...(spec.planned.limits.dwell === undefined ? {} : { dwell: spec.planned.limits.dwell }),
+        ...(spec.planned.tasks === undefined ? {} : { tasks: spec.planned.tasks }),
+        // The STUDY budget (#299): this lane notes its own running estimate on the shared ledger
+        // and stops when the RUN total crosses the cap — independent of the per-lane maxUsd above.
+        ...(deps.runBudget === undefined
+            ? {}
+            : {
+                overRunBudget: (usage) => {
+                    const estimate = estimateActorCostForExecution(usage, provider?.version ?? capModelId, provider?.executionProfile).estimatedCostUsd;
+                    const totalUsd = deps.runBudget.note(spec.planned.id, estimate);
+                    return totalUsd > deps.runBudget.maxTotalUsd
+                        ? `study budget reached: the run's estimated model spend $${round6(totalUsd)} crossed execution.caps.maxTotalUsd=$${deps.runBudget.maxTotalUsd}; this lane stops here and sibling lanes stop at their next turn`
+                        : null;
+                },
+            }),
+        ...(deps.onObservedUrl === undefined ? {} : { onObservedUrl: deps.onObservedUrl }),
+        ...(deps.onMessage === undefined ? {} : { onMessage: deps.onMessage }),
+        ...(deps.onScreenshot === undefined ? {} : { onScreenshot: deps.onScreenshot }),
+        ...(deps.onTrace === undefined
+            ? {}
+            : {
+                // Forwards the RUNNING usage as well: the lane is where both are known, and usage
+                // without it never reaches the flush — which is how the live cost stayed unknown.
+                onTrace: (items, usage, metadata) => deps.onTrace?.(spec.planned.id, items, usage, metadata),
+            }),
+    };
+}
+/**
+ * Closes the lane's model, in the order it was opened. Returns true when a provider's cleanup is
+ * unconfirmed; each failure also adds a warning.
+ */
+export async function closeParticipantModel(model, warnings) {
+    let unconfirmed = false;
+    try {
+        if (model.codexParticipant === undefined)
+            await model.provider?.close?.();
+    }
+    catch {
+        warnings.push("Model provider cleanup is unconfirmed.");
+        unconfirmed = true;
+    }
+    try {
+        const cleanup = await model.codexParticipant?.close();
+        if (cleanup?.status === "unconfirmed") {
+            warnings.push("Model provider cleanup is unconfirmed.");
+            unconfirmed = true;
+        }
+    }
+    catch {
+        warnings.push("Model provider cleanup is unconfirmed.");
+        unconfirmed = true;
+    }
+    try {
+        await model.claudeSession?.close();
+    }
+    catch {
+        warnings.push("Claude session cleanup failed; desktop cleanup will still run.");
+    }
+    return unconfirmed;
+}
+/** Prices the finished session's tokens onto its trace, writes the trace, and warns on raw screenshots. */
+export async function recordParticipantTrace(spec, deps, session, warnings) {
+    // Per-lane model-token cost ESTIMATE, attached to the trace before it is persisted (the model
+    // id is authoritative here — provider.version). Kept at the lab boundary so the pure loop
+    // never depends on the operator rate table. estimateActorCost declares absent (null) for an
+    // unknown rate / missing usage rather than guessing.
+    session.trace.estimatedCost = estimateActorCostForExecution(session.trace.tokenUsage, session.trace.ids.model, session.trace.executionProfile);
+    await writeContainedOutputFile(deps.artifactRoot, spec.traceArtifactPath, `${JSON.stringify(session.trace, null, 2)}\n`, "utf8");
+    if (session.trace.redaction.screenshots === "raw") {
+        warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. Set policies.redactScreenshots: true to blur a share-as-is bundle.");
+    }
+}
+/** The checks that keep a goal_satisfied session from counting as a pass, with their warnings. */
+export function judgeParticipantSession(session, deps, warnings) {
+    const noEngagement = session !== undefined && hollowCompletion(sessionEnding(session));
+    if (noEngagement) {
+        warnings.push("Actor returned goal_satisfied with ZERO actions and ZERO messages — it likely saw a blank or still-loading screen and stopped without engaging. NOT counted as a pass. Check the screenshot; raise execution.timeoutMs or confirm the subject painted before the first turn.");
+    }
+    const blockerReason = resolveSelfReportedBlocker(session);
+    const selfReportedBlocker = blockerReason !== undefined;
+    const reportedFriction = resolveSelfReportedFriction(session) !== undefined;
+    if (selfReportedBlocker) {
+        warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${redactText(deps.scrubKnownValues(blockerReason))}`);
+    }
+    return { noEngagement, selfReportedBlocker, reportedFriction };
+}
+export function makeCuaRunBudget(maxTotalUsd) {
+    const participantEstimates = new Map();
+    return {
+        maxTotalUsd,
+        note(participantId, estimateUsd) {
+            if (estimateUsd !== null)
+                participantEstimates.set(participantId, estimateUsd);
+            let total = 0;
+            for (const value of participantEstimates.values())
+                total += value;
+            return total;
+        },
+    };
+}

package/dist/routes/computer-use/participant-prompt.d.ts

@@ -0,0 +1,53 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { DevicePreset } from "../../lab/device-presets.js";
+import { type ResolvedPersona } from "../../lab/persona.js";
+import { type LabTask } from "../../lab/tasks.js";
+import type { DesktopParticipantRun } from "./types.js";
+export declare const DEFAULT_MISSION = "You are testing a web application. The browser is already open at the subject URL. Explore it, accomplish what the scenario asks, and stop when done.";
+/**
+ * The participant's outcome as ONE fixed first line of its last message (#570, second half). The
+ * free-text computer-use provider has no schema to fill; a fixed line is the next best thing, and
+ * the loop reads it into the trace's declaredOutcome. Prompt-only control is weak in general, so
+ * adherence is measured (declaredOutcome present or absent on the trace) and the regex over the
+ * paragraph stays as the fallback when the line is missing. This is a report format, deliberately
+ * not a behavioural instruction: it says how to label the ending, never how to act.
+ */
+export declare const CLOSING_LINE_DIRECTIVE: string;
+/** The persona id a computer-use participant gets when neither it nor its actor names one. */
+export declare const FALLBACK_PERSONA_ID = "cua-operator";
+/** Compose one lane's actor prompt: persona line + device line + mission + per-lane steer.
+ *  At N=1 (homogeneous, no roster) this reproduces the prior composeInstructions byte-for-byte. */
+export declare function composeParticipantInstructions(args: {
+    mission: string;
+    persona?: string;
+    instruction?: string;
+    /** The lab's declared protocol (#414). Only the participant-facing `goal` halves are rendered
+     *  into the prompt; the `success` criteria never appear here. */
+    tasks?: readonly LabTask[];
+    device: {
+        name: string;
+        preset: DevicePreset;
+    };
+    /** The COMPILED persona for `args.persona`, when its committed file resolved (#381). Supplying it
+     *  makes the persona shape behavior — its traits become directives in the prompt and land in
+     *  traitsApplied — instead of appearing as a bare `Persona: <id>.` label. Absent (unsafe id,
+     *  no committed file, unparseable YAML) keeps the honest fallback: the bare line and an EMPTY
+     *  traitsApplied, never fabricated traits. Resolved by the caller so this stays pure. */
+    resolvedPersona?: ResolvedPersona;
+    /**
+     * desktop-cli (#495): the surface under study is a terminal window, not a page. Said plainly
+     * because a participant whose every prior world was a browser will look for one — and because a
+     * capability nobody declares is one the recording cannot later be read against. It states that a
+     * terminal is open and NOT what to type in it: naming commands would answer the question the
+     * study is asking.
+     */
+    surface?: "desktop-cli";
+}): {
+    instructions: string;
+    persona: ActorPersonaRef;
+};
+/** Runtime-inject the persona inbox instruction into a lane's prompt (#297 slice B). The inbox URL is a
+ *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
+ *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
+ *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
+export declare function withInboxMission(spec: DesktopParticipantRun, inboxUrl: string, address?: string, receiving?: boolean): DesktopParticipantRun;

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

@@ -0,0 +1,87 @@
+// The prompt one computer-use participant reads: persona, device and surface lines, the mission,
+// the task goals, the per-participant focus and the closing-line directive. withInboxMission adds
+// the email inbox at run time. Shared by the computer-use and concurrent shared-world routes.
+import { recipientInboxUrl } from "../../comms/capture-surface.js";
+import { digestText } from "../../evidence/redaction.js";
+import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../lab/persona.js";
+import { renderTaskPrompt } from "../../lab/tasks.js";
+export const DEFAULT_MISSION = "You are testing a web application. The browser is already open at the subject URL. Explore it, accomplish what the scenario asks, and stop when done.";
+/**
+ * The participant's outcome as ONE fixed first line of its last message (#570, second half). The
+ * free-text computer-use provider has no schema to fill; a fixed line is the next best thing, and
+ * the loop reads it into the trace's declaredOutcome. Prompt-only control is weak in general, so
+ * adherence is measured (declaredOutcome present or absent on the trace) and the regex over the
+ * paragraph stays as the fallback when the line is missing. This is a report format, deliberately
+ * not a behavioural instruction: it says how to label the ending, never how to act.
+ */
+export const CLOSING_LINE_DIRECTIVE = "When you stop, make the FIRST line of your last message exactly one of these three, on its own line: " +
+    "REACHED THE GOAL. / DID NOT REACH THE GOAL. / BLOCKED. " +
+    "Then, from the next line, say what you did, what confused you, and where you hesitated.";
+/** The persona id a computer-use participant gets when neither it nor its actor names one. */
+export const FALLBACK_PERSONA_ID = "cua-operator";
+/** Compose one lane's actor prompt: persona line + device line + mission + per-lane steer.
+ *  At N=1 (homogeneous, no roster) this reproduces the prior composeInstructions byte-for-byte. */
+export function composeParticipantInstructions(args) {
+    const { name, preset } = args.device;
+    const deviceLine = preset.isMobile
+        ? `You are a mobile user on a ${name} device (${preset.width}x${preset.height} @${preset.deviceScaleFactor}x). Expect a mobile/touch layout.`
+        : `You are a desktop user (${name}, ${preset.width}x${preset.height}).`;
+    // The protocol as the PARTICIPANT reads it: numbered goals, nothing else. The success criteria
+    // are the researcher's instrument and must never reach this prompt — a persona told how it will
+    // be measured optimizes for the measurement instead of using the product (src/lab/tasks.ts).
+    const taskLines = renderTaskPrompt(args.tasks ?? []);
+    // A resolved persona contributes its compiled directives (friction tolerance, skill bias,
+    // accessibility behavior, constraints) through the SAME persona.ts compiler the terminal lane
+    // uses, so one persona file means one behavior across every route.
+    const personaLine = args.resolvedPersona
+        ? renderPersonaPromptSection(args.resolvedPersona)
+        : args.persona
+            ? `Persona: ${args.persona}.`
+            : undefined;
+    const traitsApplied = args.resolvedPersona
+        ? personaToDirectives(args.resolvedPersona).traitsApplied
+        : [];
+    const surfaceLine = args.surface === "desktop-cli"
+        ? "A terminal window is already open on this desktop, and there is a terminal in the dock at the bottom of the screen if you want another. Everything you need is on this machine; there is no browser task here."
+        : undefined;
+    const parts = [
+        personaLine,
+        deviceLine,
+        surfaceLine,
+        args.mission,
+        taskLines,
+        args.instruction ? `Lane focus: ${args.instruction}` : undefined,
+        CLOSING_LINE_DIRECTIVE,
+    ].filter((part) => Boolean(part));
+    const instructions = parts.join("\n\n");
+    return {
+        instructions,
+        persona: {
+            id: args.persona ?? FALLBACK_PERSONA_ID,
+            traitsApplied,
+            ...(args.resolvedPersona ? { brief: personaBrief(args.resolvedPersona) } : {}),
+            promptDigest: digestText(instructions, 16),
+        },
+    };
+}
+/** Runtime-inject the persona inbox instruction into a lane's prompt (#297 slice B). The inbox URL is a
+ *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
+ *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
+ *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
+export function withInboxMission(spec, inboxUrl, address, receiving = false) {
+    // No assigned identity means no participant inbox; never fall back to the shared operator view.
+    if (!address?.trim())
+        return spec;
+    // Captured mail is routed to the assigned identity. Supply that identity and inbox
+    // access without requiring the participant to wait or complete the email flow.
+    const identity = ` Your email address is ${address} — when the app asks for an email address, enter exactly that.`;
+    if (receiving)
+        return {
+            ...spec,
+            instructions: `${spec.instructions}\n\nEmail inbox:${identity} This is a fresh test identity; it does not replace an existing account's email address. When the app says it sent email, open ${inboxUrl} to check your inbox. Delivery may take a little time. Decide whether to wait or continue based on your situation. Report what you observe if mail is missing or unavailable. The inbox may block remote images or undeclared destinations; those are harness limitations.`,
+        };
+    return {
+        ...spec,
+        instructions: `${spec.instructions}\n\nEmail inbox:${identity} Your inbox is available at ${recipientInboxUrl(inboxUrl, address)} in the browser. It contains captured email addressed to your test identity. Delivery may take a little time. Decide whether to check it, wait or stop based on your situation and what you observe.`,
+    };
+}

package/dist/routes/computer-use/participant-runs.d.ts

@@ -0,0 +1,67 @@
+import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import { type LabConfig } from "../../lab/types.js";
+import { type ResolvedPersona } from "../../lab/persona.js";
+import { type RunRerunLineage } from "../../run/bundle.js";
+import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
+import { type CuaActorLabErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
+export declare function defaultSessionTimeoutMs(config: LabConfig): number;
+/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
+ *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+ *  or local-tree: provision budget + Σ state-step budgets) + the server-side
+ *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
+ *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
+ *  costs the same wall-clock room either way. */
+export declare function resolveParticipantSandboxMs(config: LabConfig): number;
+/**
+ * The in-flight participant bound a lab declares. Defaults to the participant count — every
+ * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
+ * live" into waves (#350); total session count and spend are the same either way, only wall-clock
+ * and simultaneity differ. A declared execution.concurrency is a CAP, clamped to [1, participants].
+ * The planner records it; the route may only lower it from the environment.
+ */
+export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
+/**
+ * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
+ * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
+ * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * marked $0 (dryRun: true).
+ */
+export declare function resolveCuaParticipantPlan(config: LabConfig, opts?: {
+    countOverride?: number;
+    env?: Record<string, string | undefined>;
+    dryRun?: boolean;
+    personas?: Map<string, ResolvedPersona>;
+}): CuaParticipantPlan;
+/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only — no prompt text, no secrets). */
+export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, labId: string): void;
+export declare function formatParticipantPlanEntry(entry: CuaParticipantPlanEntry): string;
+/**
+ * Compile the committed persona files the participants use, printing a warning for each one that
+ * is missing. A refusal that comes after this step reads them first, so a persona-file error still
+ * wins over it.
+ */
+export declare function compileParticipantPersonas(projectRoot: PreparedSelectedOutputDirectory, personaIds: readonly (string | undefined)[]): Promise<Map<string, ResolvedPersona>>;
+/**
+ * The participants a computer-use run drives, loaded before anything is created: committed persona
+ * files read and compiled, the pure participant table built from the plan's participants, bound
+ * and budgets (the same for dry-run and live), and a rerun narrowed to its selected participants
+ * by reading the source run.
+ */
+export declare function loadCuaParticipants(args: {
+    plan: ComputerUsePlan;
+    cwd: string;
+    projectRoot: PreparedSelectedOutputDirectory;
+    env: Record<string, string | undefined>;
+}): Promise<{
+    ok: true;
+    participantRuns: DesktopParticipantRun[];
+    participantPlan: CuaParticipantPlan;
+    rerunLineage?: RunRerunLineage;
+} | {
+    ok: false;
+    code: CuaActorLabErrorCode;
+    message: string;
+}>;
+/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+export declare function sanitizeParticipantRuns(runs: readonly DesktopParticipantRun[], scrub: (text: string) => string): void;