humanish 0.104.3 → 0.106.0

package/dist/routes/computer-use/local-tree-pack.js

@@ -0,0 +1,47 @@
+// Packing the project's working tree once per local-tree run, on the host, for every lane to upload.
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { createLocalTreeArchive } from "../../subject/local-tree-archive.js";
+import {} from "./types.js";
+/**
+ * Pack the working tree for a local-tree run and report what left the host on stderr, by counts
+ * and digest only, never paths or file names.
+ */
+export async function packRunLocalTree(hooks, config, cwd) {
+    const packLocalTree = hooks.packLocalTree ?? defaultPackLocalTree;
+    const packed = await packLocalTree({
+        root: cwd,
+        ...(config.subject.localTree?.exclude === undefined
+            ? {}
+            : { extraExclude: config.subject.localTree.exclude }),
+        ...(config.subject.localTree?.maxArchiveBytes === undefined
+            ? {}
+            : { maxArchiveBytes: config.subject.localTree.maxArchiveBytes }),
+    });
+    process.stderr.write(`humanish local-tree: packed ${packed.archive.fileCount} entries, ${packed.archive.totalBytes} bytes, archiveSha256 ${packed.archive.archiveSha256}` +
+        `${packed.archive.git ? ` (commit ${packed.archive.git.commit.slice(0, 12)}, ${packed.archive.git.dirty ? "dirty" : "clean"} working tree)` : " (not a git work tree)"}\n`);
+    return packed;
+}
+/**
+ * Default local-tree packing implementation: createLocalTreeArchive(root, opts) on the host,
+ * then a single read of the produced archive file into an ArrayBuffer for upload. The DI seam
+ * (CuaActorLabHooks.packLocalTree) overrides this in deterministic tests so they never require
+ * tar/git.
+ */
+export async function defaultPackLocalTree(args) {
+    const archive = createLocalTreeArchive(args.root, {
+        ...(args.extraExclude === undefined ? {} : { extraExclude: args.extraExclude }),
+        ...(args.maxArchiveBytes === undefined ? {} : { maxArchiveBytes: args.maxArchiveBytes }),
+    });
+    // The archive was written to a fresh mkdtemp dir (no outputPath passed above). Once the bytes
+    // are buffered, or the read fails, the on-disk copy is residue, and a packed working tree left
+    // in the host tmpdir is itself a small leak surface. Best-effort removal.
+    try {
+        const bytes = await readFile(archive.archivePath);
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        return { archive, buffer };
+    }
+    finally {
+        await rm(path.dirname(archive.archivePath), { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/routes/computer-use/local-vm.d.ts

@@ -0,0 +1,20 @@
+import type { RunLabOptions } from "../../run-lab.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type LocalFirecrackerAssets } from "../../substrates/local/firecracker-desktop.js";
+type LocalStudyOptions = RunLabOptions & {
+    config: LabConfig;
+    assets?: LocalFirecrackerAssets;
+    signal?: AbortSignal;
+};
+/** A local browser study's bindings, and the cleanup of what its lanes started. */
+export interface LocalVmStudy {
+    /** The caller's runLab options with this study's desktop lane, provider and abort signal. */
+    readonly options: RunLabOptions;
+    close(): Promise<void>;
+}
+/**
+ * Local desktop/provider composition: the options the lab is planned and run with. It throws before
+ * anything starts on a lab the local study cannot run, or on a hook only an E2B desktop calls.
+ */
+export declare function prepareLocalVmStudy(options: LocalStudyOptions): LocalVmStudy;
+export {};

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

@@ -0,0 +1,218 @@
+import { collectDesktopRecording } from "../../evidence/desktop-recording-artifact.js";
+import path from "node:path";
+import { inboxRecipientFor, PARTICIPANT_DESKTOP, } from "./participant-desktop.js";
+import { HOOK_MEMBERS, withHookOverrides } from "../../lab/bag-overrides.js";
+import { runCuaActorSession } from "../../actors/computer-use/actor.js";
+import { createLocalFirecrackerDesktop, } from "../../substrates/local/firecracker-desktop.js";
+import { localBrowserDefaults, localBrowserUnsupportedReason, } from "../../substrates/local/runtime-config.js";
+import { prepareLocalRuntime } from "../../substrates/local/runtime.js";
+import { checkRestrictedCodexAnalysisReadiness } from "../../analysis/restricted-codex.js";
+import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
+import { guestMediaConfigSchema } from "../../guest/media-config.js";
+import { startLocalCapturedInbox } from "../../substrates/local/captured-inbox.js";
+// These hooks act on an E2B desktop or the local-tree upload to it. The study runs on a
+// Firecracker desktop and never calls them, so a caller relying on one gets an error up front.
+const e2bDesktopHooks = [
+    "prepareDesktop",
+    "loadDesktopModule",
+    "onRuntimeStreamReady",
+    "packLocalTree",
+];
+function refuseE2BDesktopHooks(hooks) {
+    const present = e2bDesktopHooks.filter((name) => hooks?.[name] !== undefined);
+    if (present.length === 0)
+        return;
+    throw new Error(`A local browser study runs on a Firecracker desktop and does not call ${present.map((name) => `cuaHooks.${name}`).join(", ")}. These hooks apply only to E2B desktops.`);
+}
+function studyMedia(config) {
+    const declaredMedia = config.execution?.desktop?.media;
+    return declaredMedia === undefined
+        ? undefined
+        : guestMediaConfigSchema.parse({
+            ...declaredMedia,
+            permission: config.policies?.mediaPermission ?? "prompt",
+        });
+}
+/** The runtime image, prepared once per study on first use, after the account check. */
+function studyAssets(options, account, needsMedia) {
+    let preparing;
+    return () => (preparing ??= (async () => {
+        if (account) {
+            const readiness = await checkRestrictedCodexAnalysisReadiness({ timeoutMs: 5000 });
+            if (!readiness.ready)
+                throw new Error(`Codex account is not ready (${readiness.errorCode}). Run humanish doctor --lab <lab> before starting a local study.`);
+        }
+        return (options.assets ??
+            (await prepareLocalRuntime({
+                ...(needsMedia ? { media: true } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+                progress: (message) => process.stderr.write(`${message}\n`),
+            })));
+    })());
+}
+function mediaEvidence(media) {
+    return {
+        requested: "chromium",
+        resolved: "chromium",
+        media: {
+            ...(media.camera === undefined
+                ? {}
+                : { camera: { source: "synthetic", file: "/dev/video0" } }),
+            ...(media.microphone === undefined ? {} : { microphone: { source: "speech" } }),
+            permission: media.permission,
+            flags: media.permission === "granted" ? ["--use-fake-ui-for-media-stream"] : [],
+        },
+    };
+}
+/** One lane's Firecracker desktop and optional captured inbox, released in finalize. */
+function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
+    const { config, media, recording, state } = context;
+    let session;
+    let inbox;
+    const email = config.comms?.email;
+    const address = email?.kind === "fake" ? inboxRecipientFor(email, run.planned.id)?.address : undefined;
+    let finalizing;
+    const evidence = {
+        released: false,
+        streamUrlPresent: false,
+        stateStepRecords: [],
+        phaseRecords: [],
+    };
+    return {
+        async prepare() {
+            const runtime = await context.assets();
+            if (address && email?.kind === "fake" && email.external)
+                inbox = await startLocalCapturedInbox(email.external, address);
+            session = await createLocalFirecrackerDesktop({
+                assets: runtime,
+                ...(inbox ? { inboxUrl: inbox.url } : {}),
+                ...(media === undefined ? {} : { media }),
+                ...(recording === undefined ? {} : { recording }),
+                appUrl: run.planned.targetUrl ?? config.subject.appUrl,
+                outputRoot: path.join(context.cwd, ".humanish", "local-runtime"),
+                ...(context.signal === undefined ? {} : { signal: context.signal }),
+            });
+            state.sessions.push(session);
+            if (media !== undefined)
+                evidence.desktopBrowser = mediaEvidence(media);
+        },
+        async openSession() {
+            if (!session)
+                throw new Error("The local desktop has not been prepared.");
+            return {
+                executor: session.executor,
+                ...(inbox && address ? { inbox: { url: inbox.url, address } } : {}),
+            };
+        },
+        finalize() {
+            return (finalizing ??= (async () => {
+                try {
+                    await inbox?.close();
+                }
+                catch {
+                    state.cleanupUnconfirmed = true;
+                    warnings.push("Local inbox cleanup is unconfirmed.");
+                }
+                if (!session)
+                    return;
+                if (recording) {
+                    const desktop = session;
+                    try {
+                        evidence.recording = await collectDesktopRecording(artifactRoot, run.planned.id, (destination) => desktop.finishRecording(destination));
+                    }
+                    catch {
+                        warnings.push("Desktop video/audio recording could not be retained. Screenshots and participant evidence remain available.");
+                    }
+                }
+                try {
+                    evidence.released = (await session.close()).status === "released";
+                }
+                catch {
+                    evidence.released = false;
+                }
+                if (!evidence.released) {
+                    state.cleanupUnconfirmed = true;
+                    warnings.push("Local desktop cleanup is unconfirmed.");
+                }
+            })());
+        },
+        snapshot: () => evidence,
+    };
+}
+/** The Codex account participant, whose unconfirmed cleanup blocks the study's analysis. */
+function accountProvider(state) {
+    return {
+        async buildProvider({ executor }) {
+            const participant = createRestrictedCodexParticipant({
+                speechEnabled: executor?.speechEnabled === true,
+            });
+            state.participants.push(participant);
+            return Object.assign(participant.provider, {
+                async close() {
+                    if ((await participant.close()).status !== "confirmed") {
+                        state.cleanupUnconfirmed = true;
+                        throw new Error("Local participant cleanup is unconfirmed.");
+                    }
+                },
+            });
+        },
+    };
+}
+/**
+ * Local desktop/provider composition: the options the lab is planned and run with. It throws before
+ * anything starts on a lab the local study cannot run, or on a hook only an E2B desktop calls.
+ */
+export function prepareLocalVmStudy(options) {
+    const config = localBrowserDefaults(options.config);
+    const unsupported = localBrowserUnsupportedReason(config);
+    if (unsupported)
+        throw new Error(unsupported);
+    refuseE2BDesktopHooks(options.cuaHooks);
+    const recording = config.execution?.desktop?.recording;
+    const media = studyMedia(config);
+    const callerHooks = options.cuaHooks;
+    // A caller-supplied provider replaces the Codex account participant, so the account is
+    // neither checked nor used.
+    const account = config.actors[0]?.type === "local-agent" && callerHooks?.buildProvider === undefined;
+    const baseRunSession = callerHooks?.runSession ?? runCuaActorSession;
+    const state = { sessions: [], participants: [], cleanupUnconfirmed: false };
+    const context = {
+        config,
+        cwd: options.cwd,
+        signal: options.signal,
+        media,
+        recording,
+        assets: studyAssets(options, account, media !== undefined || recording !== undefined),
+        state,
+    };
+    const { config: _config, assets: _assets, signal: _signal, ...runOptions } = options;
+    return {
+        options: {
+            ...runOptions,
+            // Wrapped rather than spread for the same reason as cuaHooks below.
+            automaticAnalysis: withHookOverrides(options.automaticAnalysis, HOOK_MEMBERS.analysis, {
+                onStart() {
+                    if (state.cleanupUnconfirmed)
+                        throw new Error("Local study cleanup is unconfirmed.");
+                    return options.automaticAnalysis?.onStart?.();
+                },
+            }),
+            // These overrides go over the caller's hooks so this study's desktop always wins:
+            // participantDesktopOf takes [PARTICIPANT_DESKTOP] before a caller's createDesktopLane.
+            // The caller's bag may be a class instance, so it is wrapped rather than spread.
+            cuaHooks: withHookOverrides(callerHooks, HOOK_MEMBERS.cua, {
+                [PARTICIPANT_DESKTOP]: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
+                ...(account ? accountProvider(state) : {}),
+                ...(options.signal
+                    ? {
+                        runSession: (input) => baseRunSession({ ...input, signal: options.signal }),
+                    }
+                    : {}),
+            }),
+        },
+        async close() {
+            await Promise.allSettled(state.participants.map((participant) => participant.close()));
+            await Promise.allSettled(state.sessions.map((session) => session.close()));
+        },
+    };
+}

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

@@ -0,0 +1,63 @@
+import type { CuaExecutor } from "../../actors/computer-use/loop.js";
+import type { CuaActorLabHooks, DesktopParticipantRun, ParticipantRunOutcome } from "./types.js";
+import type { LabCommsEmail, LabCommsRecipient } from "../../lab/types.js";
+import type { PreparedOutputRoot } from "../../run/contained-output.js";
+/** A prepared desktop supplies only participant input/observation and its inbox location. */
+export interface ReadyParticipantDesktop {
+    executor: CuaExecutor;
+    inbox?: {
+        url: string;
+        address?: string;
+        receiving?: boolean;
+    };
+}
+/** Existing bundle fields. Provider-specific facts remain optional and must be measured. */
+export type ParticipantDesktopEvidence = {
+    /** The substrate confirmed the desktop was released (an E2B kill or a local VM shutdown). The lane
+     *  outcome records it as `killed`. */
+    released: boolean;
+} & Pick<ParticipantRunOutcome, "sandboxId" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording">;
+/**
+ * The desktop one participant runs on, owned from preparation through final evidence collection.
+ * Call methods sequentially: prepare, openSession, then finalize in a finally block.
+ * finalize must be idempotent, record unavailable evidence/cleanup as warnings, and not throw.
+ * A constructor must not acquire resources. Participant/model behavior stays in the runner.
+ *
+ * The implementations (the hosted E2B desktop, the local VM, the in-process executor) live in
+ * src/routes/computer-use/: each composes the provider primitives in src/substrates/ (the E2B
+ * sandbox, local VMs, the Shell) with route concerns such as subject provisioning, comms and the
+ * participant plan. src/substrates/ holds only the primitives.
+ */
+export interface ParticipantDesktop {
+    prepare(): Promise<void>;
+    openSession(): Promise<ReadyParticipantDesktop>;
+    finalize(options: {
+        failed: boolean;
+    }): Promise<void>;
+    snapshot(): ParticipantDesktopEvidence;
+}
+/** Builds one participant's desktop. The factory must not acquire anything; prepare does. */
+export type ParticipantDesktopFactory = (run: DesktopParticipantRun, warnings: string[], artifactRoot: PreparedOutputRoot) => ParticipantDesktop;
+/**
+ * The hook-bag member a study that owns its desktops (the local VM study) sets to its factory. A
+ * symbol keeps it out of the public CuaActorLabHooks, whose deprecated createDesktopLane takes the
+ * flat lane record; withHookOverrides forwards it like any other member of the bag.
+ */
+export declare const PARTICIPANT_DESKTOP: unique symbol;
+/** A hook bag that may carry a study's own desktop factory. */
+export type HooksWithParticipantDesktop = CuaActorLabHooks & {
+    readonly [PARTICIPANT_DESKTOP]?: ParticipantDesktopFactory;
+};
+/**
+ * The desktop factory a run uses: the study's own, else the caller's deprecated createDesktopLane,
+ * given the flat view of each run. Undefined means the route provisions its own desktop.
+ */
+export declare function participantDesktopOf(hooks: CuaActorLabHooks): ParticipantDesktopFactory | undefined;
+/** The lane's addressed comms recipient, when one exists — the gate AND the address source for the
+ *  inbox instruction (#351). A lane told to check an inbox it can never receive into would stall,
+ *  so no addressed recipient means no instruction. */
+export declare function inboxRecipientFor(commsEmail: LabCommsEmail, participantId: string): LabCommsRecipient | undefined;
+/** True when a lane has a declared comms recipient WITH an address, so the drain can actually match the
+ *  mail the persona will be told to read. Gates the inbox instruction to lanes that can receive mail —
+ *  a lane told to check an inbox it can never receive into would just stall. */
+export declare function participantHasInboxRecipient(commsEmail: LabCommsEmail, participantId: string): boolean;

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

@@ -0,0 +1,33 @@
+import { legacyHookSpecOf } from "./legacy-lane-spec.js";
+import { recipientParticipantId } from "../../lab/parse/comms.js";
+/**
+ * The hook-bag member a study that owns its desktops (the local VM study) sets to its factory. A
+ * symbol keeps it out of the public CuaActorLabHooks, whose deprecated createDesktopLane takes the
+ * flat lane record; withHookOverrides forwards it like any other member of the bag.
+ */
+export const PARTICIPANT_DESKTOP = Symbol("humanish.participantDesktop");
+/**
+ * The desktop factory a run uses: the study's own, else the caller's deprecated createDesktopLane,
+ * given the flat view of each run. Undefined means the route provisions its own desktop.
+ */
+export function participantDesktopOf(hooks) {
+    const own = hooks[PARTICIPANT_DESKTOP];
+    if (own !== undefined)
+        return own;
+    const caller = hooks.createDesktopLane;
+    return caller === undefined
+        ? undefined
+        : (run, warnings, artifactRoot) => caller(legacyHookSpecOf(run), warnings, artifactRoot);
+}
+/** The lane's addressed comms recipient, when one exists — the gate AND the address source for the
+ *  inbox instruction (#351). A lane told to check an inbox it can never receive into would stall,
+ *  so no addressed recipient means no instruction. */
+export function inboxRecipientFor(commsEmail, participantId) {
+    return (commsEmail.recipients ?? []).find((recipient) => recipientParticipantId(recipient) === participantId && recipient.address !== undefined);
+}
+/** True when a lane has a declared comms recipient WITH an address, so the drain can actually match the
+ *  mail the persona will be told to read. Gates the inbox instruction to lanes that can receive mail —
+ *  a lane told to check an inbox it can never receive into would just stall. */
+export function participantHasInboxRecipient(commsEmail, participantId) {
+    return inboxRecipientFor(commsEmail, participantId) !== undefined;
+}

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

@@ -0,0 +1,6 @@
+import { type ParticipantFacts } from "../../run/judge.js";
+import type { ParticipantRunOutcome } from "./types.js";
+/** A participant outcome's facts for the judge. */
+export declare function participantFactsOf(outcome: ParticipantRunOutcome): ParticipantFacts;
+/** Whether a participant passed. A dry-run participant passes as a contract. */
+export declare function participantOutcomeOk(outcome: ParticipantRunOutcome | undefined, dryRun: boolean): boolean;

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

@@ -0,0 +1,22 @@
+// A participant run outcome's facts for the judge (src/run/judge.ts), and the pass check built on
+// them. The bundle builders, the result, the participant runner and shared-world all read these,
+// so they sit in a file that imports only the judge and the types.
+import { participantPassed } from "../../run/judge.js";
+/** A participant outcome's facts for the judge. */
+export function participantFactsOf(outcome) {
+    return {
+        ...(outcome.session === undefined
+            ? {}
+            : { status: outcome.session.status, completionReason: outcome.session.completionReason }),
+        ...(outcome.sessionError === undefined ? {} : { sessionError: outcome.sessionError }),
+        skipped: outcome.skippedReason !== undefined,
+        noEngagement: outcome.noEngagement === true,
+        selfReportedBlocker: outcome.selfReportedBlocker === true,
+    };
+}
+/** Whether a participant passed. A dry-run participant passes as a contract. */
+export function participantOutcomeOk(outcome, dryRun) {
+    if (dryRun)
+        return true;
+    return outcome !== undefined && participantPassed(participantFactsOf(outcome));
+}

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

@@ -0,0 +1,30 @@
+import type { CuaExecutor, CuaLoopResult, CuaProvider } from "../../actors/computer-use/loop.js";
+import type { CuaActorSessionOptions } from "../../actors/computer-use/actor.js";
+import { startClaudeSession } from "../../actors/local-agent/claude-session.js";
+import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
+import type { CuaParticipantDeps, CuaRunBudget, DesktopParticipantRun } from "./types.js";
+import type { ReadyParticipantDesktop } from "./participant-desktop.js";
+/** The model a lane brings besides the default API client, and the handles its cleanup needs. */
+export interface ParticipantModel {
+    provider?: CuaProvider;
+    codexParticipant?: ReturnType<typeof createRestrictedCodexParticipant>;
+    claudeSession?: Awaited<ReturnType<typeof startClaudeSession>>;
+}
+/** Starts the lane's model: a caller's provider, the operator's Codex, a Claude session, or none. */
+export declare function startParticipantModel(spec: DesktopParticipantRun, deps: CuaParticipantDeps, executor: CuaExecutor): Promise<ParticipantModel>;
+/** The options the lane's session runs with: prompt, model settings, spend caps and callbacks. */
+export declare function participantSessionOptions(spec: DesktopParticipantRun, deps: CuaParticipantDeps, ready: ReadyParticipantDesktop, provider: CuaProvider | undefined, writeScreenshot: NonNullable<CuaActorSessionOptions["writeScreenshot"]>): CuaActorSessionOptions;
+/**
+ * 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 declare function closeParticipantModel(model: ParticipantModel, warnings: string[]): Promise<boolean>;
+/** Prices the finished session's tokens onto its trace, writes the trace, and warns on raw screenshots. */
+export declare function recordParticipantTrace(spec: DesktopParticipantRun, deps: CuaParticipantDeps, session: CuaLoopResult, warnings: string[]): Promise<void>;
+/** The checks that keep a goal_satisfied session from counting as a pass, with their warnings. */
+export declare function judgeParticipantSession(session: CuaLoopResult | undefined, deps: CuaParticipantDeps, warnings: string[]): {
+    noEngagement: boolean;
+    selfReportedBlocker: boolean;
+    reportedFriction: boolean;
+};
+export declare function makeCuaRunBudget(maxTotalUsd: number): CuaRunBudget;