humanish 0.106.1 → 0.107.0

package/dist/actors/codex/restricted-turn.d.ts

@@ -1,5 +1,6 @@
-import { type RestrictedCodexResult, type RestrictedCodexUsage } from "./restricted-policy.js";
+import { type RestrictedCodexAnalysisErrorCode, type RestrictedCodexResult, type RestrictedCodexUsage } from "./restricted-policy.js";
 import { type RestrictedCodexDeadline, type RestrictedCodexTransport } from "./restricted-transport.js";
+import { type NotificationPolicy } from "./restricted-notifications.js";
 /** What a turn reads from and reports to its session. */
 export interface RestrictedCodexTurnContext {
     readonly deadline: RestrictedCodexDeadline;
@@ -23,11 +24,23 @@ export interface RestrictedCodexTurnContext {
     reportUsage(usage: RestrictedCodexUsage | undefined, inference: RestrictedCodexUsage[] | undefined): void;
     /** The turn the session interrupts if it closes now. */
     turnStarted(turnId: string): void;
+    /** The item policy every notification's item passes, whatever its method. */
+    readonly policy: NotificationPolicy;
+    /** The session's handler for notifications that arrive before this turn is dispatched. */
+    idle(method: string, params: Record<string, unknown>): void;
+    /** Counts a notification method this humanish does not know that carried no item. */
+    recordUnknown(method: string): void;
+    /**
+     * A policy refusal: stops this request with `code`, and the session records it when the
+     * request already stopped for another reason, such as a close.
+     */
+    refuse(code: RestrictedCodexAnalysisErrorCode): void;
 }
 /**
- * Drain: every notification and tool request of one turn. Nothing is handled before `dispatched`;
- * events that arrive before turn/start's reply wait until acknowledge() and are then checked in
- * order. `finished` resolves only with a completed, validated final answer.
+ * Drain: every notification and tool request of one turn. Before `dispatched`, notifications go
+ * to the session's idle handler; events that arrive after dispatch but before turn/start's reply
+ * pass the item policy at once, then wait until acknowledge() and are checked in order.
+ * `finished` resolves only with a completed, validated final answer.
  */
 export declare class RestrictedCodexTurn {
     private readonly context;
@@ -53,6 +66,8 @@ export declare class RestrictedCodexTurn {
     acknowledge(returnedTurnId: unknown): void;
     readonly onNotification: RestrictedCodexTransport["onNotification"];
     readonly onRequest: NonNullable<RestrictedCodexTransport["onRequest"]>;
+    /** Refuses a tool request: the session records the refusal, and the transport answers it. */
+    private refuseRequest;
     readonly onRequestComplete: () => void;
     private handleTurnEvent;
     private recordUsage;

package/dist/actors/codex/restricted-turn.js

@@ -1,17 +1,11 @@
 // One restricted Codex request's turn: the notifications and tool requests the app-server sends
 // while the turn runs. Each is checked against the tool policy, the turn's identity and the output
-// limits, and any violation stops the request's deadline with a refusal code.
+// limits, and any violation stops the request's deadline with a refusal code. A policy violation
+// goes through the session, which records it when the request can no longer report it.
 import { CODEX_MAX_OUTPUT_BYTES, CODEX_MAX_REQUEST_BYTES, codexRecord, restrictedCodexUsage, toolPolicyViolation, } from "./restricted-policy.js";
 import { RestrictedCodexStop, } from "./restricted-transport.js";
+import { ANALYST_ITEM_TYPES, ANALYST_RAW_ITEM_TYPES, KNOWN_CODEX_NOTIFICATIONS, PARTICIPANT_ITEM_TYPES, PARTICIPANT_RAW_ITEM_TYPES, itemPolicyOf, } from "./restricted-notifications.js";
 const rawCompactionTypes = ["compaction", "compaction_summary", "context_compaction"];
-const analystRawItemTypes = ["message", "reasoning", ...rawCompactionTypes];
-const participantRawItemTypes = [
-    ...analystRawItemTypes,
-    "custom_tool_call",
-    "custom_tool_call_output",
-    "function_call",
-    "function_call_output",
-];
 function hasScopedIdentity(method, params, threadId, turnId) {
     if (method === "turn/started" || method === "turn/completed") {
         const id = codexRecord(params.turn).id;
@@ -28,8 +22,10 @@ function hasScopedIdentity(method, params, threadId, turnId) {
             typeof params.turnId === "string" &&
             params.turnId.length > 0 &&
             (turnId === undefined || params.turnId === turnId));
+    // Before the turn's id is known, an event that names a turn waits in the early buffer, and
+    // handleTurnEvent checks it again against the acknowledged id.
     return ((params.threadId === undefined || params.threadId === threadId) &&
-        (params.turnId === undefined || params.turnId === turnId));
+        (params.turnId === undefined || turnId === undefined || params.turnId === turnId));
 }
 function usageDelta(total, baseline) {
     const delta = {
@@ -44,9 +40,10 @@ function usageDelta(total, baseline) {
         : null;
 }
 /**
- * Drain: every notification and tool request of one turn. Nothing is handled before `dispatched`;
- * events that arrive before turn/start's reply wait until acknowledge() and are then checked in
- * order. `finished` resolves only with a completed, validated final answer.
+ * Drain: every notification and tool request of one turn. Before `dispatched`, notifications go
+ * to the session's idle handler; events that arrive after dispatch but before turn/start's reply
+ * pass the item policy at once, then wait until acknowledge() and are checked in order.
+ * `finished` resolves only with a completed, validated final answer.
  */
 export class RestrictedCodexTurn {
     context;
@@ -70,7 +67,9 @@ export class RestrictedCodexTurn {
     constructor(context) {
         this.context = context;
         this.inferenceUsage = context.participant ? [] : null;
-        this.allowedRawItemTypes = context.participant ? participantRawItemTypes : analystRawItemTypes;
+        this.allowedRawItemTypes = context.participant
+            ? PARTICIPANT_RAW_ITEM_TYPES
+            : ANALYST_RAW_ITEM_TYPES;
         this.finished = new Promise((resolve) => {
             this.resolveFinished = resolve;
         });
@@ -94,8 +93,21 @@ export class RestrictedCodexTurn {
     }
     onNotification = (method, params) => {
         const { deadline } = this.context;
-        if (!this.dispatched)
+        if (!this.dispatched) {
+            this.context.idle(method, params);
             return;
+        }
+        // The single tool-policy check, first: an event that also fails the identity or delta checks
+        // below still has its items recorded. Tool requests must fail even if the turn-start
+        // acknowledgment is lost, and every event reaches handleTurnEvent only from here, directly or
+        // through the early buffer, so no event skips it. Every item is checked, whatever the method
+        // that carries it and wherever the schema nests it.
+        const items = itemPolicyOf(method, params, this.context.policy);
+        if (toolPolicyViolation(method, codexRecord(params.item), this.allowedRawItemTypes) ||
+            items === "violation") {
+            this.context.refuse("codex_tool_call");
+            return;
+        }
         if (!hasScopedIdentity(method, params, this.context.threadId(), this.turnId ?? this.earlyTurnId)) {
             deadline.stop("codex_protocol_error");
             return;
@@ -111,13 +123,8 @@ export class RestrictedCodexTurn {
                 return;
             }
         }
-        // The single tool-policy check. Tool requests must fail even if the turn-start
-        // acknowledgment is lost, and every event reaches handleTurnEvent only from here, directly
-        // or through the early buffer, so no event skips it.
-        if (toolPolicyViolation(method, codexRecord(params.item), this.allowedRawItemTypes)) {
-            deadline.stop("codex_tool_call");
-            return;
-        }
+        if (items === "none" && !KNOWN_CODEX_NOTIFICATIONS.has(method))
+            this.context.recordUnknown(method);
         if (method === "turn/started") {
             const value = codexRecord(params.turn).id;
             if (typeof value !== "string" ||
@@ -137,7 +144,10 @@ export class RestrictedCodexTurn {
     onRequest = async (method, params) => {
         const { deadline, participant, toolCallIds } = this.context;
         const callId = params.callId;
-        if (!participant ||
+        // A request before turn/start is sent, or after the turn completed, is outside the turn.
+        if (!this.dispatched ||
+            this.completed ||
+            !participant ||
             method !== "item/tool/call" ||
             params.threadId !== this.context.threadId() ||
             typeof params.turnId !== "string" ||
@@ -150,13 +160,13 @@ export class RestrictedCodexTurn {
             callId.length > 200 ||
             toolCallIds.has(callId) ||
             this.toolRequestPending)
-            throw new RestrictedCodexStop("codex_tool_call");
+            this.refuseRequest();
         // Mark the request outstanding before waiting for a same-chunk turn/start
         // acknowledgment, so an early completion can never be accepted.
         this.toolRequestPending = true;
         const activeTurnId = this.turnId ?? this.earlyTurnId ?? (await deadline.wait(this.turnReady));
         if (params.turnId !== activeTurnId)
-            throw new RestrictedCodexStop("codex_tool_call");
+            this.refuseRequest();
         toolCallIds.add(callId);
         deadline.pause();
         const text = await deadline.wait(this.context.tool().call(params.arguments));
@@ -170,6 +180,11 @@ export class RestrictedCodexTurn {
         }
         return { success: true, contentItems: [{ type: "inputText", text }] };
     };
+    /** Refuses a tool request: the session records the refusal, and the transport answers it. */
+    refuseRequest() {
+        this.context.refuse("codex_tool_call");
+        throw new RestrictedCodexStop("codex_tool_call");
+    }
     onRequestComplete = () => {
         this.toolRequestPending = false;
     };
@@ -220,11 +235,9 @@ export class RestrictedCodexTurn {
     /** The item allowlist, the participant's one dynamic tool and the final answer's shape. */
     admitsItem(method, item) {
         const { deadline, participant } = this.context;
-        const allowedItems = participant
-            ? ["userMessage", "agentMessage", "reasoning", "contextCompaction", "dynamicToolCall"]
-            : ["userMessage", "agentMessage", "reasoning", "contextCompaction"];
+        const allowedItems = participant ? PARTICIPANT_ITEM_TYPES : ANALYST_ITEM_TYPES;
         if (!allowedItems.includes(String(item.type))) {
-            deadline.stop("codex_tool_call");
+            this.context.refuse("codex_tool_call");
             return false;
         }
         if (item.type === "dynamicToolCall" &&
@@ -232,7 +245,7 @@ export class RestrictedCodexTurn {
                 item.namespace !== null ||
                 (method === "item/started" && item.status !== "inProgress") ||
                 (method === "item/completed" && (item.status !== "completed" || item.success !== true)))) {
-            deadline.stop("codex_tool_call");
+            this.context.refuse("codex_tool_call");
             return false;
         }
         if (item.type === "agentMessage" &&

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

@@ -6,7 +6,7 @@ import { type RedactionHooks } from "../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../stop-conditions.js";
 import type { LabTask } from "../../lab/tasks.js";
 export interface CuaActorSessionOptions {
-    /** The composed mission (persona + scenario/lane instruction) handed to the model. */
+    /** The composed mission (persona + scenario/participant instruction) handed to the model. */
     instructions: string;
     /** Provenance of the persona this actor embodies (id + applied traits + prompt digest). */
     persona: ActorPersonaRef;

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

@@ -18,8 +18,8 @@ export async function runCuaActorSession(options) {
     }
     const strictSpend = options.requireReportedUsageForSpendCap === true &&
         (options.maxUsd !== undefined || options.overRunBudget !== undefined);
-    const provider = options.provider ?? buildProvider(options.openai, strictSpend);
-    const executor = options.executor ?? buildExecutor(options.desktop, options.executorOptions);
+    const provider = options.provider ?? defaultProvider(options.openai, strictSpend);
+    const executor = options.executor ?? defaultExecutor(options.desktop, options.executorOptions);
     const loopOptions = {
         instructions: options.instructions,
         provider,
@@ -61,7 +61,7 @@ export async function runCuaActorSession(options) {
     }
     return result;
 }
-function buildProvider(openai, strictSpend = false) {
+function defaultProvider(openai, strictSpend = false) {
     if (!openai) {
         throw new Error("runCuaActorSession requires either `provider` (injected) or `openai` provider options.");
     }
@@ -70,7 +70,7 @@ function buildProvider(openai, strictSpend = false) {
         ...(strictSpend ? { singleDispatch: true } : {}),
     });
 }
-function buildExecutor(desktop, executorOptions) {
+function defaultExecutor(desktop, executorOptions) {
     if (!desktop) {
         throw new Error("runCuaActorSession requires either `executor` (injected) or `desktop` to build one.");
     }

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

@@ -130,7 +130,7 @@ export function advanceBackstop(previous, turn, limits) {
     // CORROBORATION (#383). A stale frame alone is NOT evidence of a stuck agent. The frame hash is
     // a coarse whole-screen measure, and on a light-themed web app it can miss a renamed row, a new
     // list item, or an opened panel — a measured run had 9 visibly different consecutive frames hash
-    // identically while the agent was a foreign key away from finishing. Ending a lane on that
+    // identically while the agent was a foreign key away from finishing. Ending a participant on that
     // signal alone recorded working sessions as `gave_up`, capping every browser run at roughly
     // noProgressSteps turns and writing harness artifacts into evidence as actor behavior.
     //

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

@@ -28,7 +28,7 @@ export declare function declaredOutcomeOf(turn: CuaTurn): ParticipantDeclaredOut
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
  * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor
- * did stop on purpose) and the lane's credibility read turns it into a blocked participant, the
+ * did stop on purpose) and the route's credibility read turns it into a blocked participant, the
  * same path a narrated blocker takes.
  */
 export declare function participantEnded(turn: CuaTurn, declaredOutcome: ParticipantDeclaredOutcome | undefined, redactNarration: (text: string) => string): Stop;
@@ -47,7 +47,7 @@ export declare function timeLimit(session: LoopSession): Stop;
 export declare function spendLimit(session: LoopSession, estimate: number, maxUsd: number): Stop;
 export declare const nonFiniteEstimate: Stop;
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
-export declare function studySpendLimit(reason: string): Stop;
+export declare function runSpendLimit(reason: string): Stop;
 export declare const accountBilledCaps: Stop;
 export declare const adapterLimit: Stop;
 export declare const usageUnreported: Stop;

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

@@ -32,7 +32,7 @@ export function declaredOutcomeOf(turn) {
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
  * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor
- * did stop on purpose) and the lane's credibility read turns it into a blocked participant, the
+ * did stop on purpose) and the route's credibility read turns it into a blocked participant, the
  * same path a narrated blocker takes.
  */
 export function participantEnded(turn, declaredOutcome, redactNarration) {
@@ -98,7 +98,7 @@ export const nonFiniteEstimate = {
     reason: "the injected estimateTurnCostUsd returned a non-finite estimate while execution.caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
 };
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
-export function studySpendLimit(reason) {
+export function runSpendLimit(reason) {
     return { completionReason: "budget_reached", reason, stopCause: "study_spend_limit" };
 }
 // A host-authenticated provider may learn its account billing class during startup. Never price

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

@@ -8,7 +8,7 @@ export declare class LostRequestRefused extends Error {
 }
 /**
  * The spend caps, checked before the next provider request so a model stuck retrying cannot keep
- * spending. The lane cap stops the session once the running estimate crosses maxUsd; a null
+ * spending. The per-participant cap stops the session once the running estimate crosses maxUsd; a null
  * estimate cannot trip it, because preflight guaranteed a rate. The study budget (#299) is checked
  * next.
  */

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

@@ -1,6 +1,6 @@
 import * as stops from "./ending.js";
 import { notice } from "./trace.js";
-// The spend guards. The lane cap (maxUsd) and the study budget (overRunBudget) are priced from
+// The spend guards. The per-participant cap (maxUsd) and the study budget (overRunBudget) are priced from
 // the usage each reply reports, plus a worst-case charge booked for each request lost without a
 // reply. A request whose cost is unknown and unbounded stops a capped session before the next one.
 /** Thrown through the provider when a lost attempt may not be sent again; carries the stop. */
@@ -13,7 +13,7 @@ export class LostRequestRefused extends Error {
 }
 /**
  * The spend caps, checked before the next provider request so a model stuck retrying cannot keep
- * spending. The lane cap stops the session once the running estimate crosses maxUsd; a null
+ * spending. The per-participant cap stops the session once the running estimate crosses maxUsd; a null
  * estimate cannot trip it, because preflight guaranteed a rate. The study budget (#299) is checked
  * next.
  */
@@ -29,7 +29,7 @@ export function spendStop(session) {
     if (overRunBudget) {
         const runStop = overRunBudget(session.usage.forCap());
         if (runStop !== null)
-            return stops.studySpendLimit(runStop);
+            return stops.runSpendLimit(runStop);
     }
     return undefined;
 }

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

@@ -37,7 +37,7 @@ export class TraceRecorder {
 export function statusForCompletionReason(reason) {
     switch (reason) {
         case "goal_satisfied":
-        case "turn_completed": // turn_completed is a Codex-lane reason; this loop emits goal_satisfied
+        case "turn_completed": // turn_completed is a Codex reason; this loop emits goal_satisfied
             return "passed";
         // A session that ran out of time or budget did not reach its goal, whatever it achieved along
         // the way. Calling that `passed` is how a truncated study came to be reported as a green one —
@@ -56,7 +56,7 @@ export function statusForCompletionReason(reason) {
             return "abandoned";
         // Only the harness failing is a harness failure.
         case "actor_error":
-        case "step_failed": // step_failed is the scripted-browser lane's reason; this loop never emits it
+        case "step_failed": // step_failed is the scripted-browser route's reason; this loop never emits it
         case "harness_error":
             return "failed";
     }

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

@@ -229,7 +229,7 @@ export interface CuaProvider {
     nextTurn(req: CuaTurnRequest, signal: AbortSignal, spend?: CuaSpendGate): Promise<CuaTurn>;
     /** Optional read-only closing report. Implementations must disable tools and make no retries. */
     debrief?: ((req: CuaTurnRequest, signal: AbortSignal) => Promise<CuaTurn>) | undefined;
-    /** Release lane-owned model resources. Idempotent; reject if cleanup is unconfirmed. */
+    /** Release the participant's model resources. Idempotent; reject if cleanup is unconfirmed. */
     close?(): Promise<void>;
 }
 /** The desktop side of the loop. */
@@ -261,7 +261,7 @@ export interface CuaLoopOptions {
     /**
      * Per-attempt bound on the provider call (#469), so a hung request is told apart from a
      * participant still thinking. A stalled turn is retried once with a notice; a second stall ends
-     * the lane as harness_error.
+     * the participant as harness_error.
      */
     turnTimeoutMs?: number;
     /**
@@ -308,7 +308,7 @@ export interface CuaLoopOptions {
     writeScreenshot?: (name: string, bytes: Buffer) => Promise<string>;
     /**
      * Deterministic harness-owned success guards. Evaluated after the initial observation and after
-     * every post-action observation, before another model turn is requested. This keeps a lane from
+     * every post-action observation, before another model turn is requested. This keeps a participant from
      * wandering after the product already reached an app-visible endpoint.
      */
     stopWhen?: StopWhen;
@@ -346,8 +346,8 @@ export interface CuaLoopOptions {
      */
     estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
     /**
-     * RUN-LEVEL spend guard (#299): called with this lane's running usage each turn, at the same
-     * point the per-lane cap is checked. Returns a human-readable reason when the STUDY's shared
+     * RUN-LEVEL spend guard (#299): called with this participant's running usage each turn, at the same
+     * point the per-participant cap is checked. Returns a human-readable reason when the STUDY's shared
      * budget is exhausted, else null. On a non-null return the loop stops with `budget_reached`
      * regardless of material progress — a study-level stop is a recruiting decision hitting its
      * limit, not this participant's runaway, so it never reads as `gave_up`.
@@ -368,6 +368,9 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public shared-world handoff (src/routes/shared-world/handoff.ts)
      * latches the host participant's lobby URL and checks that each follower reached the same lobby.
+     *
+     * @deprecated Wrap the executor's `observe` and read `url` from each observation it returns. The
+     * next minor removes this option.
      */
     onObservedUrl?: (url: string | undefined) => void;
     /**
@@ -378,6 +381,9 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public handoff scans the host's narration for the lobby code,
      * because the E2B desktop's CDP URL read behind onObservedUrl is unreliable.
+     *
+     * @deprecated Wrap the provider's `nextTurn` and read `reasoning` and `message` from each turn it
+     * returns. The next minor removes this option.
      */
     onMessage?: (text: string) => void;
     /**
@@ -387,6 +393,9 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public handoff reads the lobby code off each participant's own
      * frame until that participant has one: the host's latch, or a follower's convergence observation.
+     *
+     * @deprecated Wrap the executor's `observe` and read `screenshot` from each observation it
+     * returns. The next minor removes this option.
      */
     onScreenshot?: (frame: Buffer) => void;
     /**

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

@@ -187,11 +187,11 @@ function stopBeforeActing(session, turn, turnNumber) {
         return stops.accountBilledCaps;
     if (turn.interruption !== undefined) {
         // Preserve usage and partial narration of an interrupted response. Its usage still counts
-        // toward the study budget; when that exhausts it, sibling lanes stop, so this trace says why.
-        const studyStop = overRunBudget?.(session.usage.forCap());
+        // toward the study budget; when that exhausts it, sibling participants stop, so this trace says why.
+        const runBudgetStop = overRunBudget?.(session.usage.forCap());
         recordNarration(session, turn, turnNumber, "interrupted");
-        if (studyStop != null) {
-            session.trace.record("notice", () => notice("warn", "study budget reached during an interrupted response", studyStop));
+        if (runBudgetStop != null) {
+            session.trace.record("notice", () => notice("warn", "study budget reached during an interrupted response", runBudgetStop));
         }
         return stops.providerInterrupted(turn.interruption);
     }

package/dist/actors/computer-use/openai-provider.d.ts

@@ -46,7 +46,7 @@ export declare const RETRY_AFTER_CAP_MS = 60000;
  * Parse a Retry-After header (delay-seconds or an HTTP-date) into milliseconds from `now`;
  * undefined when absent or unreadable. OpenAI's 2026-09-02 change added `429 slow_down` and
  * `503 server_is_overloaded`, both of which may carry it; a fixed 200/400/800 ms backoff against
- * a 20 s hint burns every retry inside the hint and ends the lane for nothing.
+ * a 20 s hint burns every retry inside the hint and ends the participant's session for nothing.
  */
 export declare function retryAfterMs(value: string | null | undefined, now: number): number | undefined;
 /**

package/dist/actors/computer-use/openai-provider.js

@@ -93,7 +93,7 @@ export const RETRY_AFTER_CAP_MS = 60_000;
  * Parse a Retry-After header (delay-seconds or an HTTP-date) into milliseconds from `now`;
  * undefined when absent or unreadable. OpenAI's 2026-09-02 change added `429 slow_down` and
  * `503 server_is_overloaded`, both of which may carry it; a fixed 200/400/800 ms backoff against
- * a 20 s hint burns every retry inside the hint and ends the lane for nothing.
+ * a 20 s hint burns every retry inside the hint and ends the participant's session for nothing.
  */
 export function retryAfterMs(value, now) {
     if (value === null || value === undefined)
@@ -109,7 +109,7 @@ export function retryAfterMs(value, now) {
     return Math.max(0, at - now);
 }
 /**
- * The provider error codes a lane's reason may name. Read from a non-ok body, which is never
+ * The provider error codes a participant's reason may name. Read from a non-ok body, which is never
  * kept or logged (it can echo the input); only a code on this list crosses over.
  */
 const NAMED_PROVIDER_ERROR_CODES = [

package/dist/actors/contract.d.ts

@@ -24,7 +24,7 @@ export type ActorStatus = (typeof ACTOR_STATUSES)[number];
 /**
  * What the PARTICIPANT said happened, in a field rather than a paragraph (#570). Providers whose
  * reply is schema-constrained (the local-agent routes) fill it on their final turn; a free-text
- * provider leaves it absent and the lane falls back to reading the closing message. `reached`:
+ * provider leaves it absent and the route falls back to reading the closing message. `reached`:
  * the task is finished. `blocked`: something in the app stopped the participant. `not_reached`:
  * the participant stopped for another reason (gave up, ran out of ideas).
  */
@@ -193,7 +193,9 @@ export interface ActorRuntimeProvenance {
     observedVersion?: string;
     versionStatus: "unobserved" | "verified" | "failed";
     requestedModel?: string;
-    modelStatus: "declared" | "runtime_default_unobserved";
+    /** Where requestedModel came from. Bundles written before humanish always passed a model record
+     *  `runtime_default_unobserved`, with no requestedModel. */
+    modelStatus: "declared" | "humanish_default" | "runtime_default_unobserved";
     requestedReasoningEffort?: string;
     /** Codex turn.completed aggregates requests; it cannot establish per-request pricing tiers. */
     usageGranularity: "runtime_turn";
@@ -231,7 +233,7 @@ export interface ActorTrace {
     /**
      * ADDITIVE + OPTIONAL record of HOW the model was asked to run (humanish.model-settings.v1,
      * #497). `ids.model` says which model; this says the reasoning effort the request actually
-     * carried. Present on lanes whose provider declares settings; absent everywhere else and on
+     * carried. Present on traces whose provider declares settings; absent everywhere else and on
      * every pre-existing bundle, and its absence is tolerated by verify.
      *
      * It exists because effort was a silent constant: unreachable from a lab, so every run took the
@@ -248,7 +250,7 @@ export interface ActorTrace {
      * ADDITIVE + OPTIONAL affordance record (humanish.affordance-use.v1, #369): which KIND of route
      * this actor took — pointer, keyboard, url-navigation, script-execution, devtools,
      * browser-internal, observation — as per-class counts over the run's dispatched actions.
-     * Present on computer-use lanes that dispatched at least one action; absent elsewhere and on
+     * Present on computer-use traces that dispatched at least one action; absent elsewhere and on
      * every pre-existing bundle (its absence is tolerated by verify). The harness records the class
      * and states NO verdict: whether a class is faithful depends on the population the study
      * declares, which is product semantics and belongs to the adopter's scorer. See
@@ -266,7 +268,7 @@ export interface ActorTrace {
     /**
      * ADDITIVE + OPTIONAL (#570): the outcome the participant declared on its final turn, when its
      * provider's reply carries the field. Absent on free-text providers and on every older bundle.
-     * The lane reads this before it reads the closing paragraph; three regex patches in one month
+     * The route reads this before it reads the closing paragraph; three regex patches in one month
      * (#453, #549, #565) each fixed a false refusal and each left the next shape unhandled.
      */
     declaredOutcome?: ParticipantDeclaredOutcome;
@@ -287,11 +289,11 @@ export interface ActorTrace {
      *  Known tokenUsage remains usable as a partial total. Absence is not proof of completeness. */
     interactionUsageIncomplete?: true;
     /**
-     * ADDITIVE + OPTIONAL token-derived cost ESTIMATE for this lane (humanish.actor-estimated-cost.v1).
+     * ADDITIVE + OPTIONAL token-derived cost ESTIMATE for this trace (humanish.actor-estimated-cost.v1).
      * Distinct from `tokenUsage.costUsd`, which is RESERVED for a real provider-returned charge: a
      * bare `costUsd` always means "the provider billed this", while `estimatedCost.estimatedCostUsd`
      * is a rate-table multiply named honestly as an estimate (invariant 6). Absent on the Codex
-     * app-server and scripted lanes and on every pre-existing bundle; the terminal lane records a
+     * app-server and scripted traces and on every pre-existing bundle; the terminal trace records a
      * null estimate. Its absence is tolerated by verify (fail-open on display). A `null`
      * estimatedCostUsd is DECLARED ABSENT (unknown rate / no usage), never 0.
      */

package/dist/actors/local-agent/cli.js

@@ -18,7 +18,7 @@
 //
 // WHERE IT IS SAFE, and this inverts the intuitive reading: the local agent only DECIDES. humanish
 // executes the action inside the desktop sandbox, so nothing the persona chooses ever runs on the
-// operator's machine. The same trick on the TERMINAL lane would be the opposite — it would move
+// operator's machine. The same trick on the TERMINAL route would be the opposite — it would move
 // code execution out of the sandbox and onto a real disk — which is why this is a computer-use
 // provider and nothing else. Even so, these are coding agents with their own shell and file tools,
 // so each one is spawned tool-restricted, in a scratch directory, with a per-turn timeout.

package/dist/actors/scripted-browser/actor.d.ts

@@ -10,10 +10,10 @@ export interface ScriptedBrowserSessionOptions {
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
     /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
-    /** ONE session per surface lane. */
+    /** ONE session per surface. */
     surface: BrowserSurface;
     /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
-     *  (the step manifest IS the "prompt" — no model prompt exists on this lane). */
+     *  (the step manifest IS the "prompt" — no model prompt exists on this route). */
     persona: ActorPersonaRef;
     /** Journey wall-clock budget in ms; the lab route passes execution.timeoutMs or 300_000. */
     timeoutMs: number;

package/dist/actors/scripted-browser/journey.js

@@ -1,6 +1,7 @@
 // Parse a scenario's `browser.steps` into a BrowserPersonaJourney: the actions, text assertions and
 // expectations the scripted browser runs. The journey is the actor's whole behavior.
 import path from "node:path";
+import { isRecord } from "../../run/type-guards.js";
 export function parseBrowserPersonaJourneyFromScenario(args) {
     if (!isRecord(args.raw)) {
         return {};
@@ -86,7 +87,16 @@ function parseBrowserPersonaStep(rawStep, index) {
     const selector = stringValue(source.selector);
     const pathValue = stringValue(source.path);
     const value = stringValue(source.value);
+    const key = stringValue(source.key);
     const expectation = browserStepExpectationValue(source.expect ?? source.expectation);
+    if (action === "press" && !key) {
+        return { failure: `${id} press action requires key (for example Enter).` };
+    }
+    if (action !== "press" && "key" in source) {
+        return {
+            failure: `${id} sets key, which only a press step sends. Supported actions: ${SUPPORTED_ACTIONS}.`,
+        };
+    }
     if (action === "fill" && !selector) {
         return { failure: `${id} fill action requires selector.` };
     }
@@ -105,12 +115,14 @@ function parseBrowserPersonaStep(rawStep, index) {
             ...(pathValue === undefined ? {} : { path: pathValue }),
             ...(selector === undefined ? {} : { selector }),
             ...(value === undefined ? {} : { value }),
+            ...(key === undefined ? {} : { key }),
         },
     };
 }
 function hasInlineBrowserSteps(value) {
     return Array.isArray(value) && value.some((entry) => isRecord(entry) && isRecord(entry.browser));
 }
+const SUPPORTED_ACTIONS = "goto, fill, click, press, assertText, waitForText, waitForSelector";
 function browserPersonaActionValue(value) {
     if (typeof value !== "string") {
         return null;
@@ -121,8 +133,10 @@ function browserPersonaActionValue(value) {
         .replace(/[-_\s]+/g, "");
     if (normalized === "goto" || normalized === "open" || normalized === "navigate")
         return "goto";
-    if (normalized === "click" || normalized === "press")
+    if (normalized === "click")
         return "click";
+    if (normalized === "press")
+        return "press";
     if (normalized === "fill" || normalized === "type")
         return "fill";
     if (normalized === "asserttext" || normalized === "expecttext")
@@ -152,9 +166,6 @@ function browserStepExpectationValue(value) {
     };
     return Object.keys(expectation).length === 0 ? undefined : expectation;
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function stringValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }

package/dist/actors/scripted-browser/steps.js

@@ -52,6 +52,24 @@ export async function executeBrowserPersonaStep(args) {
         await target.click({ timeout: stepTimeoutMs });
         await args.page.waitForTimeout(300);
     }
+    else if (args.step.action === "press") {
+        if (!args.step.key) {
+            throw new Error(`${args.step.id} press step is missing key`);
+        }
+        // With a selector, Playwright focuses that element first; without one, the key goes to
+        // whatever has focus, such as the input a fill step just typed into.
+        if (args.step.selector) {
+            const target = args.page.locator(args.step.selector).first();
+            if ((await target.count()) === 0) {
+                throw new Error(`${args.step.id} press step found no target`);
+            }
+            await target.press(args.step.key, { timeout: stepTimeoutMs });
+        }
+        else {
+            await args.page.keyboard.press(args.step.key);
+        }
+        await args.page.waitForTimeout(300);
+    }
     else if (args.step.action === "assertText" || args.step.action === "waitForText") {
         const expectedText = args.step.expectation?.text ?? args.step.value;
         if (!expectedText) {