humanish 0.105.0 → 0.106.1

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

@@ -0,0 +1,248 @@
+import { CuaProviderError } from "./provider-error.js";
+import { runActionBatch } from "./loop/actions.js";
+import { advanceBackstop, startBackstop } from "./loop/backstop.js";
+import { requestDebrief } from "./loop/debrief.js";
+import * as stops from "./loop/ending.js";
+import { declaredOutcomeOf } from "./loop/ending.js";
+import { DesktopObserver } from "./loop/observation.js";
+import { retryAfterOutputLimit } from "./loop/output-limit.js";
+import { requestTurn } from "./loop/provider-call.js";
+import { LoopSession } from "./loop/session.js";
+import { spendStop, unknownSpendStop } from "./loop/spend.js";
+import { accountBillingConflicts } from "./loop/usage.js";
+import { loopResult, notice } from "./loop/trace.js";
+export { describeCuaAction } from "./loop/actions.js";
+export { stableProgressKey } from "./loop/backstop.js";
+export { validClosingReport } from "./loop/debrief.js";
+/**
+ * Drive the loop to one explicit completion and return its CuaLoopResult: status, completion
+ * reason, public reason and ActorTrace. Model-authored text passes through redactNarration before
+ * it is recorded; screenshots are persisted raw unless redactScreenshots is set.
+ */
+export async function runComputerUseLoop(options) {
+    refuseAccountBilledCaps(options);
+    const session = new LoopSession(options);
+    const conversation = {
+        previousResponseId: undefined,
+        previousExecution: undefined,
+        acknowledgedSafetyChecks: undefined,
+        contextHint: undefined,
+    };
+    let stop;
+    try {
+        stop = session.conclude(await runTurns(session, conversation));
+    }
+    catch (error) {
+        stop = session.conclude(stops.stopForError(session, error));
+    }
+    // A structured stop earns the debrief even if recording its evidence then failed.
+    const debrief = session.debriefTrigger === undefined
+        ? undefined
+        : await requestDebrief(session, conversation, session.debriefTrigger);
+    return loopResult(session, stop, debrief);
+}
+/**
+ * Observe, then turn after turn: ask the provider, vet the reply, act, observe again and fold
+ * the result into the backstop. Every exit returns the Stop that ends the session; errors thrown
+ * from a port end it through stopForError. Bounded by wall-clock and the friction backstops,
+ * never a turn count.
+ */
+async function runTurns(session, conversation) {
+    const observer = new DesktopObserver(session);
+    const opening = await observer.checkpoint(0);
+    if ("stop" in opening)
+        return opening.stop;
+    let { observation } = opening;
+    if (opening.hint !== undefined)
+        conversation.contextHint = opening.hint;
+    let backstop = startBackstop(observation);
+    let turnNumber = 0;
+    // A request whose reply was cut off by the output limit, to be sent once more.
+    let resend;
+    for (;;) {
+        const halt = haltBeforeTurn(session);
+        if (halt !== undefined)
+            return halt;
+        turnNumber += 1;
+        const retrying = resend !== undefined;
+        const request = resend ?? nextRequest(session, conversation, observation);
+        resend = undefined;
+        session.phase = `requesting provider turn ${turnNumber}`;
+        const reply = await requestTurn(session, request, turnNumber);
+        if ("stop" in reply)
+            return reply.stop;
+        const { turn } = reply;
+        const cutOff = retryAfterOutputLimit(session, turn, turnNumber, retrying);
+        if (cutOff === "retry") {
+            recordNarration(session, turn, turnNumber, "interrupted");
+            resend = request;
+            continue;
+        }
+        if (cutOff !== undefined)
+            return cutOff;
+        recordTurn(session, conversation, observer, request, turn);
+        const refused = stopBeforeActing(session, turn, turnNumber);
+        if (refused !== undefined)
+            return refused;
+        forwardNarration(session, turn);
+        const overBudget = spendStop(session);
+        if (overBudget !== undefined)
+            return overBudget;
+        recordNarration(session, turn, turnNumber, "completed");
+        const blocked = reviewSafetyChecks(session, conversation, turn);
+        if (blocked !== undefined)
+            return blocked;
+        if (turn.done || turn.actions.length === 0) {
+            // The declared outcome is kept even if redacting the participant's summary fails.
+            session.declaredOutcome = declaredOutcomeOf(turn);
+            const ended = stops.participantEnded(turn, session.declaredOutcome, (text) => session.redactNarration(text));
+            await observer.observeFinalTasks(turnNumber);
+            return ended;
+        }
+        const batch = await runActionBatch(session, turn.actions);
+        conversation.previousExecution = batch.execution;
+        const checkpoint = await observer.checkpoint(turnNumber);
+        if ("stop" in checkpoint)
+            return checkpoint.stop;
+        observation = checkpoint.observation;
+        const step = advanceBackstop(backstop, { actions: turn.actions, observation, heardNewSpeech: observer.heardNewSpeech }, { idleSteps: session.idleSteps, noProgressSteps: session.noProgressSteps });
+        backstop = step.backstop;
+        const stalled = applyBackstop(session, conversation, step, [checkpoint.hint, batch.hint]);
+        if (stalled !== undefined)
+            return stalled;
+        const unknownSpend = unknownSpendStop(session);
+        if (unknownSpend !== undefined)
+            return unknownSpend;
+    }
+}
+/**
+ * Count the turn's idle and no-progress flags, stage every hint for the next request, and stop
+ * when a streak tripped. The
+ * turn's own hints (a dwell window, a rejected action) come first, then the backstop's nudges.
+ */
+function applyBackstop(session, conversation, step, turnHints) {
+    if (step.idle)
+        session.trace.bump("idleTurns");
+    if (!step.progressed)
+        session.trace.bump("noProgressTurns");
+    const hints = [...turnHints.filter((hint) => hint !== undefined), ...step.hints];
+    if (hints.length > 0)
+        conversation.contextHint = hints.join(" ");
+    return step.tripReason === undefined ? undefined : stops.gaveUp(session, step.tripReason);
+}
+function refuseAccountBilledCaps(options) {
+    if (accountBillingConflicts(options.provider, options)) {
+        throw new CuaProviderError("request_rejected", {
+            dispatched: false,
+            usageComplete: false,
+            cleanup: "confirmed",
+        });
+    }
+}
+function haltBeforeTurn(session) {
+    if (session.signal?.aborted)
+        return stops.harnessAborted;
+    if (session.remaining() < 0)
+        return stops.timeLimit(session);
+    return undefined;
+}
+/** Build the next request; the context hint and safety acknowledgements ride it once. */
+function nextRequest(session, conversation, observation) {
+    const request = {
+        instructions: session.settings.instructions,
+        observation,
+        ...(session.provider.requestPolicy !== "fail_closed" ||
+            conversation.previousExecution === undefined
+            ? {}
+            : { previousExecution: conversation.previousExecution }),
+    };
+    if (conversation.previousResponseId !== undefined)
+        request.previousResponseId = conversation.previousResponseId;
+    if (conversation.contextHint !== undefined)
+        request.contextHint = conversation.contextHint;
+    if (conversation.acknowledgedSafetyChecks !== undefined)
+        request.acknowledgedSafetyChecks = conversation.acknowledgedSafetyChecks;
+    conversation.contextHint = undefined;
+    conversation.acknowledgedSafetyChecks = undefined;
+    return request;
+}
+function recordTurn(session, conversation, observer, request, turn) {
+    const hint = request.contextHint;
+    if (hint)
+        session.trace.record("notice", () => ({
+            title: "Participant context hint",
+            text: session.redactNarration(hint),
+            lifecycle: "completed",
+        }));
+    session.trace.bump("turns");
+    observer.speechDelivered();
+    conversation.previousResponseId = turn.responseId ?? conversation.previousResponseId;
+    session.lastResponseId = turn.responseId ?? session.lastResponseId;
+    session.usage.record(turn, "interaction");
+}
+/** Stops for a reply that must not be acted on: account billing, interruption, unknown usage. */
+function stopBeforeActing(session, turn, turnNumber) {
+    const { overRunBudget } = session.settings;
+    if (accountBillingConflicts(session.provider, session.settings))
+        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());
+        recordNarration(session, turn, turnNumber, "interrupted");
+        if (studyStop != null) {
+            session.trace.record("notice", () => notice("warn", "study budget reached during an interrupted response", studyStop));
+        }
+        return stops.providerInterrupted(turn.interruption);
+    }
+    if (session.requiresUsage && session.usage.unavailableForCap()) {
+        session.usage.markUnreported();
+        return stops.usageUnreported;
+    }
+    return undefined;
+}
+/** Hand the turn's narration to the onMessage hook; see CuaLoopOptions.onMessage. */
+function forwardNarration(session, turn) {
+    const { onMessage } = session.settings;
+    const narration = [turn.reasoning, turn.message]
+        .filter((t) => typeof t === "string" && t.length > 0)
+        .join("\n");
+    if (narration.length > 0)
+        onMessage?.(narration);
+}
+function recordNarration(session, turn, turnNumber, response) {
+    const interrupted = response === "interrupted";
+    const prefix = interrupted ? "incomplete " : "";
+    const status = interrupted ? { status: "warn" } : {};
+    const { reasoning, message } = turn;
+    if (reasoning) {
+        session.trace.record("reasoning", () => ({
+            lifecycle: "completed",
+            ...status,
+            title: `${prefix}reasoning turn ${turnNumber}`,
+            text: session.redactNarration(reasoning),
+        }));
+        session.trace.bump("reasonings");
+    }
+    if (message) {
+        session.trace.record("message", () => ({
+            lifecycle: "completed",
+            ...status,
+            title: `${prefix}message turn ${turnNumber}`,
+            text: session.redactNarration(message),
+        }));
+        session.trace.bump("messages");
+    }
+}
+/** Unacknowledged safety checks pause the run; acknowledged ones ride the next request. */
+function reviewSafetyChecks(session, conversation, turn) {
+    if (turn.pendingSafetyChecks.length === 0)
+        return undefined;
+    const { acknowledgeSafetyChecks } = session;
+    const acks = acknowledgeSafetyChecks(turn.pendingSafetyChecks);
+    if (acks === null || acks.length === 0) {
+        return stops.blockedOnSafetyChecks(session.settings.redaction.redactText(turn.pendingSafetyChecks.map((check) => check.code).join(", ")));
+    }
+    conversation.acknowledgedSafetyChecks = acks;
+    return undefined;
+}

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

@@ -0,0 +1,107 @@
+import type { ActorCapabilities } from "../contract.js";
+import type { CuaProvider } from "./loop.js";
+import { type OpenAiReasoningSummary } from "./openai-wire.js";
+import type { ReasoningEffort } from "../reasoning-effort.js";
+export declare const OPENAI_RESPONSES_CU_CAPABILITIES: ActorCapabilities;
+export declare const DEFAULT_OPENAI_CU_MODEL = "gpt-5.6-sol";
+/**
+ * The effort a request carries when a lab declares none. Exported because a default that only
+ * exists as a literal inside the provider is exactly how it stayed invisible: the lab surface has
+ * to be able to say what will actually run (#497).
+ */
+export declare const DEFAULT_OPENAI_CU_REASONING_EFFORT: ReasoningEffort;
+/** The opt-in gate for response wire capture: a directory path, or unset for off. */
+export declare const WIRE_CAPTURE_ENV = "HUMANISH_CUA_WIRE_CAPTURE_DIR";
+/**
+ * Deep-copy a captured wire value with every string — object keys included —
+ * passed through the shared redactText, so a secret-shaped echo in a response
+ * can never persist to disk. Pure; non-string primitives pass through unchanged.
+ */
+export declare function redactWireJson(value: unknown): unknown;
+/** Deterministic ordered capture file name for the 1-based nth provider call. */
+export declare function wireCaptureFileName(callNumber: number): string;
+/**
+ * The minimal slice of the fetch contract the shim depends on. Injecting this
+ * (rather than importing a fetch type) keeps the module dependency-free and lets
+ * CI tests run with a fake that never touches the network.
+ */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    /** Optional so a scripted fake need not carry headers; the real fetch Response does. */
+    headers?: {
+        get(name: string): string | null;
+    };
+}>;
+/** The longest wait a provider's Retry-After hint can impose on one retry. */
+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.
+ */
+export declare function retryAfterMs(value: string | null | undefined, now: number): number | undefined;
+/**
+ * What a 400 names about itself: an allowlisted `code`, else `invalid_request_error` when that is
+ * the `type` (several 400s carry `code: null`), plus the rejected parameter's path. Only these
+ * identifier-shaped fields cross over; the message can echo the input and never does.
+ */
+export declare function requestRejectionDetail(bodyText: string): string | undefined;
+export declare function namedProviderErrorCode(bodyText: string): string | undefined;
+export interface OpenAiResponsesProviderOptions {
+    apiKey: string;
+    model?: string;
+    /**
+     * How hard the model is asked to think per turn. Absent = the provider default below.
+     * The vocabulary is the documented union across models; SUPPORT IS MODEL-DEPENDENT, so an
+     * unsupported level surfaces as the provider's own first-turn error rather than a silent
+     * downgrade to something the trace would then misreport. See src/actors/reasoning-effort.ts.
+     */
+    reasoningEffort?: ReasoningEffort;
+    /** Optional positive integer output limit per response, including reasoning. Not a spend cap. */
+    maxOutputTokens?: number;
+    /**
+     * Reasoning-summary capture (#427). Defaults to "auto" (the provider picks the best
+     * summarizer the model supports); "off" never asks. If the account/model rejects the
+     * request (e.g. an org not verified for reasoning summaries), the provider latches
+     * summaries off for the session and retries the same turn — the run degrades to
+     * exactly the pre-#427 behavior instead of failing after spend. Absence stays honest:
+     * no summary means no `reasoning` trace items and `counts.reasonings` stays 0.
+     */
+    reasoningSummary?: OpenAiReasoningSummary | "off";
+    safetyIdentifier?: string;
+    endpoint?: string;
+    fetchFn?: FetchLike;
+    maxRetries?: number;
+    /** Internal strict-accounting policy: one HTTP dispatch, including policy negotiation.
+     * Used by sessions with requireReportedUsageForSpendCap; missing usage must stop before another
+     * paid request. */
+    singleDispatch?: boolean;
+    delayFn?: (ms: number) => Promise<void>;
+    zeroDataRetention?: boolean;
+    /**
+     * Environment for the wire-capture gate (HUMANISH_CUA_WIRE_CAPTURE_DIR — see the
+     * module header). Injectable so deterministic tests control the gate without
+     * mutating process.env. Defaults to process.env.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Create a stateful CuaProvider backed by the OpenAI Responses API. The first
+ * turn opens a session (buildInitialRequest); subsequent turns send the prior
+ * call outputs (with the latest screenshot) and thread state via
+ * previous_response_id, transparently falling back to explicit-context mode if
+ * the account rejects server-side retention. Transient HTTP failures are retried
+ * with exponential backoff. Returns ONLY a CuaTurn from nextTurn; nothing
+ * sensitive (the key, the request body, the screenshot, the raw response body)
+ * is ever returned or logged.
+ */
+export declare function createOpenAiResponsesProvider(options: OpenAiResponsesProviderOptions): CuaProvider;