humanish 0.104.3 → 0.106.0

package/dist/comms/setup.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { COMMS_CONFIG_PATH, readCommsConnections } from "./connections.js";
+import { discoverProviderKeys, listUserKeys, probeKeySources, } from "../keys/key-resolution.js";
+import { COMMS_PROVIDERS, commsProviderLabel, DEFAULT_COMMS_PROVIDER, } from "./providers.js";
+import { createReceivingAdapter } from "./receiving-runtime.js";
+import { RECEIVING_SCOPE_UNSUPPORTED } from "./receiving-types.js";
+import { parseLabConfig } from "../lab/config.js";
+import { resolveLabManifest } from "../lab/discover.js";
+import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+export async function checkCommsConnection(args) {
+    const base = {
+        schema: "humanish.comms-check.v1",
+        ok: false,
+        connection: args.connection ?? DEFAULT_COMMS_PROVIDER.id,
+        online: args.online === true,
+        credentialPresent: false,
+        authenticated: null,
+        ready: null,
+        permissions: "unknown",
+        capacity: "unknown",
+        checkedAt: null,
+        code: "configuration_unavailable",
+        message: "Could not read this email connection. Check Connections or .humanish/local/comms.yaml.",
+    };
+    let adapter;
+    let label = DEFAULT_COMMS_PROVIDER.label;
+    try {
+        const connection = (await readCommsConnections(args.cwd)).connections[base.connection];
+        if (!connection)
+            return {
+                ...base,
+                ready: false,
+                code: "connection_missing",
+                message: `Save an ${DEFAULT_COMMS_PROVIDER.label} connection in Connections first.`,
+            };
+        label = commsProviderLabel(connection.provider);
+        const env = { ...args.env };
+        await discoverProviderKeys({
+            cwd: args.cwd,
+            env,
+            announce: () => { },
+            ...(args.keyDeps === undefined ? {} : { deps: args.keyDeps }),
+        });
+        const key = env[connection.apiKeyEnv]?.trim();
+        if (!key)
+            return {
+                ...base,
+                ready: false,
+                code: "credential_missing",
+                message: "The configured credential is missing. Add it in Connections or provide it with --env-file.",
+            };
+        base.credentialPresent = true;
+        if (!args.online)
+            return {
+                ...base,
+                ok: true,
+                code: "local_setup_present",
+                message: "Connection and key are present. Authentication, permissions, capacity and delivery are not checked. Use --online for a read-only authentication check.",
+            };
+        base.checkedAt = new Date().toISOString();
+        const makeAdapter = args.makeAdapter ?? ((apiKey) => createReceivingAdapter(connection, apiKey));
+        adapter = makeAdapter(key);
+        await adapter.authenticate({ timeoutMs: 8_000 });
+        return {
+            ...base,
+            ok: true,
+            authenticated: true,
+            code: "authenticated",
+            message: "Authentication passed. Inbox permissions, available capacity and delivery remain untested; this check created no resources.",
+        };
+    }
+    catch (error) {
+        // Only a code the adapter declares may reach the result; anything else stays generic.
+        const raw = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+        const code = typeof raw === "string" && adapter?.codes.has(raw) === true ? raw : "check_unavailable";
+        // The adapter authenticated the key but rejected its scope.
+        if (code === RECEIVING_SCOPE_UNSUPPORTED)
+            return {
+                ...base,
+                ready: false,
+                authenticated: true,
+                code: "scope_unsupported",
+                message: "Authenticated, but this release requires an organization-scoped key to acquire fresh inboxes.",
+            };
+        const rejected = code === adapter?.authRejectedCode;
+        return {
+            ...base,
+            code,
+            ...(rejected ? { authenticated: false, ready: false } : {}),
+            message: rejected
+                ? `${label} rejected this credential or its permissions. Check the effective key source and replace it if needed. The saved key was kept.`
+                : "The connection check could not complete. The saved key was kept; retry when the provider is available.",
+        };
+    }
+}
+export async function receivingRequiredKey(cwd, connectionName) {
+    try {
+        return (await readCommsConnections(cwd)).connections[connectionName]?.apiKeyEnv ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Save a local copy, never rewrite a committed manifest or silently shadow it by handle. */
+export async function configureCommsLab(args) {
+    const base = { schema: "humanish.comms-configure.v1", ok: false, applied: false };
+    try {
+        const connection = (await readCommsConnections(args.cwd)).connections[args.connection];
+        if (!connection)
+            return { ...base, message: "Save the selected connection first." };
+        const source = await resolveLabManifest(args.cwd, args.lab);
+        if (!source.ok)
+            return { ...base, message: "The selected lab could not be read safely." };
+        const root = await prepareSelectedOutputDirectory(args.cwd, args.cwd);
+        const rel = path
+            .relative(root.requestedPath, path.resolve(args.cwd, source.path))
+            .replace(/\\/g, "/");
+        const bytes = await readContainedRegularFile(root, rel);
+        if (!bytes || bytes.length > 1024 * 1024)
+            return { ...base, message: "The lab is missing or too large." };
+        const raw = parse(bytes.toString("utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return { ...base, message: "The lab must be a mapping." };
+        const lab = raw;
+        const existing = lab.comms;
+        if (existing?.email && existing.email.connection === undefined)
+            return {
+                ...base,
+                message: "This lab uses local capture. Preserve it or make a separate lab before selecting real email.",
+            };
+        lab.comms = { ...existing, email: { ...existing?.email, connection: args.connection } };
+        const validated = parseLabConfig(lab);
+        if (!validated.ok)
+            return {
+                ...base,
+                message: "This lab does not support real email receiving. Use a hosted computer-use app-url, clone or local-tree route; shared-world must be concurrent.",
+            };
+        const filename = path
+            .basename(source.path)
+            .replace(/\.ya?ml$/, "")
+            .replace(/-receiving$/, "") + "-receiving.yaml";
+        if (!/^[A-Za-z0-9_][A-Za-z0-9._-]{0,110}\.yaml$/.test(filename))
+            return { ...base, message: "Use a simple lab filename before configuring email." };
+        const destination = `.humanish/local/labs/${filename}`;
+        if (rel === destination)
+            return {
+                ...base,
+                message: "This is already the local receiving copy. Select its original lab to configure a separate copy, or edit this manifest directly.",
+            };
+        let prior;
+        try {
+            prior = await readContainedRegularFile(root, destination);
+        }
+        catch {
+            return { ...base, message: "The local destination could not be read safely." };
+        }
+        const content = stringify(lab);
+        const token = createHash("sha256")
+            .update(bytes)
+            .update("\0")
+            .update(prior ?? "missing")
+            .update("\0")
+            .update(destination)
+            .update("\0")
+            .update(args.connection)
+            .digest("hex");
+        const plan = {
+            ...base,
+            ok: true,
+            path: destination,
+            planToken: token,
+            connection: args.connection,
+            message: `Save ${destination} with fresh ${commsProviderLabel(connection.provider)} inboxes. Email is hosted; actor and analysis models may see content. Recordings require local review and cannot be automatically published. Provider charges are separate. Launch this exact path.`,
+        };
+        if (!args.apply)
+            return plan;
+        if (args.planToken !== undefined && args.planToken !== token)
+            return {
+                ...base,
+                message: "The lab or destination changed since preview. Preview again before saving.",
+            };
+        const directory = await prepareManagedHumanishOutputDirectory(args.cwd, "local", "labs");
+        const lockPath = path.join(directory.physicalPath, ".comms-configure.lock");
+        const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        const identity = await lock.stat();
+        try {
+            const currentSource = await readContainedRegularFile(root, rel);
+            const currentDestination = await readContainedRegularFile(root, destination);
+            if (!currentSource?.equals(bytes) ||
+                (prior === null ? currentDestination !== null : !currentDestination?.equals(prior)))
+                return { ...base, message: "Files changed while saving. Preview again." };
+            await writeContainedOutputFile(directory, filename, content, "utf8");
+        }
+        finally {
+            await lock.close();
+            await assertPreparedSelectedOutputDirectory(directory);
+            const current = await lstat(lockPath);
+            if (current.dev === identity.dev && current.ino === identity.ino)
+                await unlink(lockPath);
+        }
+        return {
+            ...plan,
+            applied: true,
+            message: `Saved ${destination}. Start that exact lab path; the original manifest was preserved.`,
+        };
+    }
+    catch {
+        return {
+            ...base,
+            message: "Could not configure this lab safely. Check configuration, paths and permissions; no provider resources were created.",
+        };
+    }
+}
+export async function readCommsSetup(cwd, env, deps) {
+    const base = {
+        schema: "humanish.comms-setup.v1",
+        configPath: COMMS_CONFIG_PATH,
+        providers: COMMS_PROVIDERS,
+    };
+    const keyEnv = DEFAULT_COMMS_PROVIDER.keyEnv;
+    const credential = {
+        present: false,
+        source: null,
+        stored: false,
+        strict: env.HUMANISH_STRICT_KEYS?.trim() === "1",
+        explicitlyEmpty: env[keyEnv] !== undefined && env[keyEnv].trim() === "",
+    };
+    try {
+        const config = await readCommsConnections(cwd);
+        const [probe] = await probeKeySources([keyEnv], {
+            cwd,
+            env,
+            ...(deps ? { deps } : {}),
+        });
+        credential.source = probe?.source ?? null;
+        credential.present = credential.source !== null;
+        credential.stored = listUserKeys(env, deps).includes(keyEnv);
+        return {
+            ...base,
+            ok: true,
+            connections: Object.entries(config.connections).map(([name, value]) => ({ name, ...value })),
+            credential,
+            message: "Checks are local. Authentication, permissions, capacity and delivery have not been verified.",
+        };
+    }
+    catch {
+        return {
+            ...base,
+            ok: false,
+            connections: [],
+            credential,
+            message: "Could not read connection setup. Check .humanish/local/comms.yaml and key-store permissions. No changes were made.",
+        };
+    }
+}

package/dist/comms/thread-evidence.d.ts

@@ -0,0 +1,28 @@
+import type { CommsMessage } from "./types.js";
+declare const COMMS_THREAD_SCHEMA = "humanish.comms-thread.v1";
+interface CommsThreadEntry {
+    id: string;
+    channel: CommsMessage["channel"];
+    /** sha256-16 of the raw sender address. */
+    fromDigest: string;
+    /** sha256-16 of each recipient inbox address. */
+    toDigests: string[];
+    /** sha256-16 of the subject (non-reversible for a PII subject; correlates identical subjects). */
+    subjectDigest?: string;
+    /** sha256-16 of each actionable link (high-entropy → non-reversible). */
+    linkDigests: string[];
+    /** COUNT ONLY — a short OTP's digest is reversible, so the code itself never lands here. */
+    codeCount: number;
+    sentAt: number;
+    deliveredAt: number;
+}
+export interface CommsThreadArtifact {
+    schema: typeof COMMS_THREAD_SCHEMA;
+    channel: CommsMessage["channel"];
+    count: number;
+    thread: CommsThreadEntry[];
+}
+/** Project polled inbox messages into the digest-only thread artifact. Pure; the caller writes it into
+ *  the run dir and registers it as an adapter-artifact. */
+export declare function buildCommsThreadArtifact(messages: CommsMessage[]): CommsThreadArtifact;
+export {};

package/dist/comms/thread-evidence.js

@@ -0,0 +1,30 @@
+// Digest-only evidence for a captured comms thread (#297). Proves "the verification mail arrived and
+// the persona could act on it" WITHOUT persisting raw PHI. Written as an adapter-artifact
+// (humanish.comms-thread.v1), so it inherits the bundle's existence-verify + public-safety scan.
+//
+// Digest discipline (deliberate, see below): addresses + links are digested (high entropy → the digest
+// is not reversible). The subject is DIGESTED too, not stored as text — redactText only scrubs
+// secret-SHAPED tokens/paths, not free-form PII (the #108 gap), so a subject like "results for <name>"
+// would pass through verbatim; a sha256-16 keeps a PII subject non-reversible while still letting you
+// correlate identical subjects. OTP CODES are a COUNT ONLY, never digested — a sha256 of a 6-digit code
+// has ~10^6 preimages and is trivially brute-forced back to the code, so a "code digest" would leak it.
+// Net: NO raw address/subject/link/OTP text ever lands in the artifact. Same caution as the lobby code.
+import { digestText } from "../evidence/redaction.js";
+const COMMS_THREAD_SCHEMA = "humanish.comms-thread.v1";
+/** Project polled inbox messages into the digest-only thread artifact. Pure; the caller writes it into
+ *  the run dir and registers it as an adapter-artifact. */
+export function buildCommsThreadArtifact(messages) {
+    const channel = messages[0]?.channel ?? "email";
+    const thread = messages.map((message) => ({
+        id: message.id,
+        channel: message.channel,
+        fromDigest: digestText(message.from, 16),
+        toDigests: message.to.map((address) => address.digest),
+        ...(message.subject === undefined ? {} : { subjectDigest: digestText(message.subject, 16) }),
+        linkDigests: message.links.map((link) => digestText(link, 16)),
+        codeCount: message.codes.length,
+        sentAt: message.sentAt,
+        deliveredAt: message.deliveredAt,
+    }));
+    return { schema: COMMS_THREAD_SCHEMA, channel, count: thread.length, thread };
+}

package/dist/comms/types.d.ts

@@ -0,0 +1,76 @@
+export type CommsChannelKind = "email" | "sms";
+/**
+ * One participant's inbox identity. `value` is runtime-only; `digest` is the only form meant to
+ * persist.
+ */
+export interface CommsAddress {
+    channel: CommsChannelKind;
+    /** Which participant owns this inbox. */
+    participantId: string;
+    /** Runtime-only raw address, e.g. user-07@example.test | +15550137. */
+    value: string;
+    /** sha256-short(value) — the only form persisted (redaction.digestText). */
+    digest: string;
+}
+/** Runtime-only captured raster attachment. Bytes never enter digest-only evidence. */
+export interface CommsInlineImage {
+    contentId: string;
+    contentType: string;
+    base64: string;
+}
+/** A message that arrived to (or was sent from) an inbox. Body/links/codes are runtime-only. */
+export interface CommsMessage {
+    id: string;
+    channel: CommsChannelKind;
+    /** Raw sender — an app-under-test address, or another actor's address. Runtime-only. */
+    from: string;
+    /** Resolved recipient inboxes this message was delivered to. */
+    to: CommsAddress[];
+    subject?: string;
+    /** Runtime-only for real; local-only for fake (never a share path without redaction — #108). */
+    body: string;
+    inlineImages?: CommsInlineImage[];
+    /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
+    links: string[];
+    /** OTP-shaped tokens extracted from the body. Runtime-only; literal-scrub targets. */
+    codes: string[];
+    sentAt: number;
+    deliveredAt: number;
+}
+/** An actor sending OUT (a reply/compose); recipients are known CommsAddresses. */
+export interface OutboundMessage {
+    from: CommsAddress;
+    to: CommsAddress[];
+    subject?: string;
+    body: string;
+    inlineImages?: CommsInlineImage[];
+}
+/** A raw inbound from an INGRESS (the vendor-neutral email catch, an SMTP sink, …): recipients are
+ *  raw address strings the bus resolves against its provisioned inboxes. */
+export interface InboundRaw {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+    inlineImages?: CommsInlineImage[];
+}
+/**
+ * The captured-mail port. Only the in-process FakeInbox implements it; real email goes through
+ * ReceivingAdapter (receiving-types.ts). It is async so a network adapter could fit without
+ * changing callers; the fake resolves immediately.
+ */
+export interface CommsChannel {
+    readonly channel: CommsChannelKind;
+    readonly kind: "fake" | "real";
+    /** Mint an inbox for a participant (address generated). Idempotent per participant. */
+    provision(participantId: string): Promise<CommsAddress>;
+    /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */
+    send(message: OutboundMessage): Promise<CommsMessage>;
+    /** Route a raw ingress delivery (app-under-test → recipient strings). Returns the messages that
+     *  matched a provisioned inbox (unmatched recipients are dropped — no inbox to deliver to). */
+    deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
+    /** New messages delivered to `address` since `since` (exclusive), oldest-first. Drives the surface. */
+    poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;
+    /** Release every provisioned inbox. */
+    teardown(): Promise<void>;
+}

package/dist/comms/types.js

@@ -0,0 +1,8 @@
+// The addressed message bus for captured mail (#297): the email or SMS a persona receives off the
+// app, as a testable surface. One port, addressed by lane, so the inbox surface and the evidence
+// writer read messages without knowing how they were captured.
+//
+// PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the
+// address DIGEST (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
+// a verification link / OTP has "no secret shape" (like the lobby code) → literal-scrub + digest.
+export {};

package/dist/deprecated.d.ts

@@ -0,0 +1,90 @@
+import { type CuaActorSessionOptions } from "./actors/computer-use/actor.js";
+import type { CuaLoopResult } from "./actors/computer-use/loop.js";
+import type { AutomaticAnalysisHooks as AnalysisHooks } from "./analysis/automatic-completion.js";
+import type { BrowserLabAdapterHooks as BrowserAdapterHooks } from "./lab/adapter-extension.js";
+import { type LabBackend as Backend } from "./lab/plan.js";
+import type { LabConfig } from "./lab/types.js";
+import type { CuaActorLabHooks as CuaHooks, CuaActorLabResult as CuaResult, RunCuaActorLabOptions as CuaOptions } from "./routes/computer-use/types.js";
+import type { RunScriptedBrowserLabOptions as ScriptedOptions, ScriptedBrowserLabHooks as ScriptedHooks, ScriptedBrowserLabResult as ScriptedResult } from "./routes/scripted/types.js";
+import type { ConcurrentSharedWorldLabResult as SharedWorldResult, RunConcurrentSharedWorldLabOptions as SharedWorldOptions, SharedWorldLabHooks as SharedWorldHooks } from "./routes/shared-world/types.js";
+import type { RunTerminalProductLabOptions as TerminalOptions, TerminalProductLabHooks as TerminalHooks, TerminalProductLabResult as TerminalResult } from "./routes/terminal/types.js";
+import type { RunOptions as PreviewOptions, RunResult as PreviewResult } from "./run/results.js";
+import type { SubjectPhaseEvent as PhaseEvent } from "./subject/steps.js";
+/**
+ * @deprecated Use `runComputerUseLoop` with `createOpenAiResponsesProvider({ singleDispatch: true })`,
+ * the strict-spend composition in docs/contracts/schemas.md.
+ */
+export declare function runCuaActorSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"computer-use">`. */
+export declare function runCuaActorLab(options: CuaOptions): Promise<CuaResult>;
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"scripted">`. */
+export declare function runScriptedBrowserLab(options: ScriptedOptions): Promise<ScriptedResult>;
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"terminal">`. */
+export declare function runTerminalProductLab(options: TerminalOptions): Promise<TerminalResult>;
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"shared-world">`. */
+export declare function runConcurrentSharedWorld(options: SharedWorldOptions): Promise<SharedWorldResult>;
+/** @deprecated Use `runLab(config, options)` on a `this-repo` lab; its result is `LabResult<"preview">`. */
+export declare function runDryRun(options: PreviewOptions): Promise<PreviewResult>;
+/** @deprecated Use `routeOf(config)` on the lab. This goes in the next minor. */
+export declare function actorResolvesToTerminal(type: string | undefined): boolean;
+/**
+ * @deprecated Use the `plan` `LabEvent` from `RunLabOptions.onEvent`, which lists every
+ * participant. This goes in the next minor.
+ */
+export declare function cuaLaneCount(config: LabConfig): number;
+/**
+ * @deprecated Use `parseLabConfig`, which refuses a seat entry that is not same-origin loopback.
+ * This goes in the next minor.
+ */
+export declare function resolveSeatUrl(serveUrl: string, entry: string | undefined): string | null;
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export declare function cuaLaneValidationReason(config: LabConfig): string | null;
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export declare function sharedWorldValidationReason(config: LabConfig): string | null;
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export declare function concurrentSharedWorldValidationReason(config: LabConfig): string | null;
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export declare function externalPublicSharedWorldValidationReason(config: LabConfig): string | null;
+/**
+ * @deprecated Use `RunLabOptions.dryRun`; without it, `scenario.mode` decides. This goes in the
+ * next minor.
+ */
+export declare function resolveLabDryRun(config: LabConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
+/** @deprecated `parseLabConfig` refuses a roster larger than this. This goes in the next minor. */
+export declare const MAX_CUA_LANES = 16;
+/** @deprecated Use `LabRoute`. `LabOutcome.backend` and this type go in the next minor. */
+export type LabBackend = Backend;
+/** @deprecated Use `RunLabOptions` with `runLab`. */
+export type RunCuaActorLabOptions = CuaOptions;
+/** @deprecated Use `LabResult<"computer-use">`. */
+export type CuaActorLabResult = CuaResult;
+/** @deprecated Use `RunLabOptions` with `runLab`. */
+export type RunScriptedBrowserLabOptions = ScriptedOptions;
+/** @deprecated Use `LabResult<"scripted">`. */
+export type ScriptedBrowserLabResult = ScriptedResult;
+/** @deprecated Use `RunLabOptions` with `runLab`. */
+export type RunTerminalProductLabOptions = TerminalOptions;
+/** @deprecated Use `LabResult<"terminal">`. */
+export type TerminalProductLabResult = TerminalResult;
+/** @deprecated Use `RunLabOptions` with `runLab`. */
+export type RunConcurrentSharedWorldLabOptions = SharedWorldOptions;
+/** @deprecated Use `LabResult<"shared-world">`. */
+export type ConcurrentSharedWorldLabResult = SharedWorldResult;
+/** @deprecated Use `RunLabOptions` with `runLab`. */
+export type RunOptions = PreviewOptions;
+/** @deprecated Use `LabResult<"preview">`. */
+export type RunResult = PreviewResult;
+/** @deprecated Use the typed homes on `RunLabOptions` (`scorer`, `createProvider`, `inProcess`, `prepareDesktop`, `env`, `onEvent`, `onStream`). */
+export type CuaActorLabHooks = CuaHooks;
+/** @deprecated Use the typed homes on `RunLabOptions` (`prepareDesktop`, `env`). */
+export type ScriptedBrowserLabHooks = ScriptedHooks;
+/** @deprecated Use the typed homes on `RunLabOptions` (`scorer`, `env`). */
+export type TerminalProductLabHooks = TerminalHooks;
+/** @deprecated Use the typed homes on `RunLabOptions` (`scorer`, `prepareDesktop`, `env`, `onEvent`, `onStream`). */
+export type SharedWorldLabHooks = SharedWorldHooks;
+/** @deprecated Use `RunLabOptions.scorer`, an `AdapterScorerModule`. */
+export type BrowserLabAdapterHooks = BrowserAdapterHooks;
+/** @deprecated Use the `subject-phase` `LabEvent` through `RunLabOptions.onEvent`. */
+export type SubjectPhaseEvent = PhaseEvent;
+/** @deprecated Use `RunLabOptions.onEvent` (`analysis-started`, `analysis-finished`) and `analysisSignal`. */
+export type AutomaticAnalysisHooks = AnalysisHooks;

package/dist/deprecated.js

@@ -0,0 +1,106 @@
+// The exports this minor deprecates and the next minor removes (docs/contracts/schemas.md,
+// "Library options"). Each function warns once per process and then runs unchanged. Each type is
+// an alias of the type it always was, and each constant has the value it always had. Internal code
+// calls the original functions, so only a package caller sees a warning.
+import { runCuaActorSession as cuaActorSession, } from "./actors/computer-use/actor.js";
+import { resolveLabDryRun as labDryRun } from "./lab/plan.js";
+import { actorResolvesToTerminal as resolvesToTerminal, cuaLaneCount as laneCount, MAX_CUA_LANES as laneCap, resolveSeatUrl as seatUrl, } from "./lab/routing.js";
+import { concurrentSharedWorldValidationReason as concurrentSharedWorldReason, cuaLaneValidationReason as laneRosterReason, externalPublicSharedWorldValidationReason as externalPublicSharedWorldReason, sharedWorldValidationReason as sharedWorldReason, } from "./lab/validation.js";
+import { runCuaActorLab as cuaActorLab } from "./routes/computer-use/route.js";
+import { runScriptedBrowserLab as scriptedBrowserLab } from "./routes/scripted/route.js";
+import { runConcurrentSharedWorld as concurrentSharedWorld } from "./routes/shared-world/route.js";
+import { runTerminalProductLab as terminalProductLab } from "./routes/terminal/route.js";
+import { runDryRun as dryRun } from "./run/dry-run.js";
+const warned = new Set();
+function deprecated(name, replacement) {
+    if (warned.has(name))
+        return;
+    warned.add(name);
+    process.emitWarning(`${name} is deprecated and is removed in the next minor. Use ${replacement}.`, { type: "DeprecationWarning", code: "HUMANISH_DEPRECATED_EXPORT" });
+}
+const RUN_LAB = "runLab(config, options); its result is LabResult<route>";
+/**
+ * @deprecated Use `runComputerUseLoop` with `createOpenAiResponsesProvider({ singleDispatch: true })`,
+ * the strict-spend composition in docs/contracts/schemas.md.
+ */
+export function runCuaActorSession(options) {
+    deprecated("runCuaActorSession", "runComputerUseLoop with createOpenAiResponsesProvider({ singleDispatch: true }) (the strict-spend composition in docs/contracts/schemas.md)");
+    return cuaActorSession(options);
+}
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"computer-use">`. */
+export function runCuaActorLab(options) {
+    deprecated("runCuaActorLab", RUN_LAB);
+    return cuaActorLab(options);
+}
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"scripted">`. */
+export function runScriptedBrowserLab(options) {
+    deprecated("runScriptedBrowserLab", RUN_LAB);
+    return scriptedBrowserLab(options);
+}
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"terminal">`. */
+export function runTerminalProductLab(options) {
+    deprecated("runTerminalProductLab", RUN_LAB);
+    return terminalProductLab(options);
+}
+/** @deprecated Use `runLab(config, options)`; its result is `LabResult<"shared-world">`. */
+export function runConcurrentSharedWorld(options) {
+    deprecated("runConcurrentSharedWorld", RUN_LAB);
+    return concurrentSharedWorld(options);
+}
+/** @deprecated Use `runLab(config, options)` on a `this-repo` lab; its result is `LabResult<"preview">`. */
+export function runDryRun(options) {
+    deprecated("runDryRun", RUN_LAB);
+    return dryRun(options);
+}
+const PARSE_REASON = "parseLabConfig, which returns the same reason";
+/** @deprecated Use `routeOf(config)` on the lab. This goes in the next minor. */
+export function actorResolvesToTerminal(type) {
+    deprecated("actorResolvesToTerminal", "routeOf(config) on the lab");
+    return resolvesToTerminal(type);
+}
+/**
+ * @deprecated Use the `plan` `LabEvent` from `RunLabOptions.onEvent`, which lists every
+ * participant. This goes in the next minor.
+ */
+export function cuaLaneCount(config) {
+    deprecated("cuaLaneCount", "the plan LabEvent from RunLabOptions.onEvent, which lists every participant");
+    return laneCount(config);
+}
+/**
+ * @deprecated Use `parseLabConfig`, which refuses a seat entry that is not same-origin loopback.
+ * This goes in the next minor.
+ */
+export function resolveSeatUrl(serveUrl, entry) {
+    deprecated("resolveSeatUrl", "parseLabConfig, which refuses a participant entry that is not same-origin loopback");
+    return seatUrl(serveUrl, entry);
+}
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export function cuaLaneValidationReason(config) {
+    deprecated("cuaLaneValidationReason", PARSE_REASON);
+    return laneRosterReason(config);
+}
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export function sharedWorldValidationReason(config) {
+    deprecated("sharedWorldValidationReason", PARSE_REASON);
+    return sharedWorldReason(config);
+}
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export function concurrentSharedWorldValidationReason(config) {
+    deprecated("concurrentSharedWorldValidationReason", PARSE_REASON);
+    return concurrentSharedWorldReason(config);
+}
+/** @deprecated Use `parseLabConfig`, which returns the same reason. This goes in the next minor. */
+export function externalPublicSharedWorldValidationReason(config) {
+    deprecated("externalPublicSharedWorldValidationReason", PARSE_REASON);
+    return externalPublicSharedWorldReason(config);
+}
+/**
+ * @deprecated Use `RunLabOptions.dryRun`; without it, `scenario.mode` decides. This goes in the
+ * next minor.
+ */
+export function resolveLabDryRun(config, override, fallback) {
+    deprecated("resolveLabDryRun", "RunLabOptions.dryRun; without it, scenario.mode decides");
+    return labDryRun(config, override, fallback);
+}
+/** @deprecated `parseLabConfig` refuses a roster larger than this. This goes in the next minor. */
+export const MAX_CUA_LANES = laneCap;

package/dist/evidence/browser-hygiene.js

@@ -0,0 +1,42 @@
+/**
+ * Browser chrome that belongs to the host environment (update prompts, password
+ * save bubbles, first-run UI) pollutes product evidence. Keep these knobs in one
+ * place so browser-backed lanes can prefer product pixels over browser UI.
+ */
+export const CHROMIUM_EVIDENCE_HYGIENE_FLAGS = [
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-default-apps",
+    "--disable-domain-reliability",
+    "--disable-extensions",
+    "--disable-sync",
+    "--no-default-browser-check",
+    "--no-first-run",
+    "--password-store=basic",
+    "--use-mock-keychain",
+];
+const CHROMIUM_EVIDENCE_PROFILE_PREFERENCES = {
+    autofill: {
+        credit_card_enabled: false,
+        profile_enabled: false,
+    },
+    browser: {
+        check_default_browser: false,
+        // Linux CSD adds 8px to Chrome's minimum width. Use the window manager's
+        // frame so the 500px desktop floor can be physically contained.
+        custom_chrome_frame: false,
+    },
+    credentials_enable_service: false,
+    payments: {
+        can_make_payment_enabled: false,
+    },
+    profile: {
+        default_content_setting_values: {
+            notifications: 2,
+        },
+        password_manager_enabled: false,
+    },
+};
+export function chromiumEvidenceProfilePreferencesJson() {
+    return JSON.stringify(CHROMIUM_EVIDENCE_PROFILE_PREFERENCES);
+}