humanish 0.107.0 → 0.109.0

package/dist/lab/plan.js

@@ -1,132 +0,0 @@
-// The route decision. A lab's route follows from its composition (subject.source,
-// execution.target, the first actor's registered lane, subject.topology), never from a declared
-// kind. This is the only function that decides it.
-import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
-import { callerDrivingOf, planComputerUseLab } from "../routes/computer-use/plan.js";
-import { injectedBrowser, planScriptedLab } from "../routes/scripted/plan.js";
-import { planSharedWorldLab } from "../routes/shared-world/plan.js";
-import { planTerminalLab } from "../routes/terminal/plan.js";
-import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
-import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
-import { planBase } from "./plan-base.js";
-import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
-/**
- * The route a config takes. It never refuses: a config no route can run still gets the route
- * whose own checks refuse it with the most precise reason.
- */
-export function routeOf(config) {
-    const source = config.subject.source;
-    // A scripted-browser actor on a loopback app or a provisioned clone replays committed steps.
-    if (isScriptedBrowserComposition(config))
-        return "scripted";
-    // A terminal-product subject goes to the terminal route even with an unregistered actor, so that
-    // route refuses the actor instead of another route running something else.
-    if (isTerminalProductComposition(config) || source === "terminal-product")
-        return "terminal";
-    // Checked before computer use: the same composition without the topology declaration runs
-    // independent participants.
-    if (isSharedWorldComposition(config))
-        return "shared-world";
-    // A CLI studied at a desktop is a computer-use study whose subject is a terminal window.
-    if (source === "desktop-cli")
-        return "computer-use";
-    // Every other app-url, clone, local-app or local-tree config goes to computer use, including
-    // ones with an unknown actor: that route refuses the actor, where the preview route would run
-    // no participant at all.
-    if (isComputerUseComposition(config) ||
-        source === "app-url" ||
-        source === "clone" ||
-        source === "local-app" ||
-        source === "local-tree")
-        return "computer-use";
-    // this-repo runs the synthetic preview.
-    return "preview";
-}
-/** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
-export function resolveLabDryRun(config, override, fallback) {
-    if (override !== undefined) {
-        return override;
-    }
-    if (config.scenario?.mode === "live") {
-        return false;
-    }
-    if (config.scenario?.mode === "dry-run") {
-        return true;
-    }
-    return fallback;
-}
-/**
- * The preview route's refusals before a run starts, in its order: real email receiving, then
- * analysis, then tasks. Each would otherwise be silently ignored by a synthetic run.
- */
-function planPreview(config, options, input) {
-    const refuse = (code, message) => ({
-        ok: false,
-        refusal: { route: "preview", code, message },
-    });
-    if (String(config.comms?.email?.kind) === "real")
-        return refuse("HUMANISH_LAB_COMMS_UNSUPPORTED", "Real email receiving is unsupported on the preview route. Use a supported hosted computer-use lab.");
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    if (!analysis.ok)
-        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
-    const unsupported = automaticAnalysisRouteReason(config);
-    if (unsupported)
-        return refuse("HUMANISH_LAB_ANALYSIS_UNSUPPORTED", unsupported);
-    const tasksReason = taskProtocolValidationReason(config);
-    if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
-    const participantCount = options.count ?? config.actors[0]?.count ?? 4;
-    if (!Number.isSafeInteger(participantCount) || participantCount < 1)
-        return refuse("HUMANISH_INVALID_SIM_COUNT", "count must be a positive integer.");
-    if (!input.dryRun)
-        return refuse("HUMANISH_LIVE_RUN_UNIMPLEMENTED", THIS_REPO_DRY_RUN_ONLY);
-    return {
-        ok: true,
-        plan: {
-            ...planBase(config, { ...input, analysis }),
-            route: "preview",
-            dryRun: true,
-            participantCount,
-        },
-    };
-}
-/**
- * The plan a lab runs under, built without reading files, env or the network. Each route's planner
- * makes every refusal that route makes, in the route's order and with its codes and messages; the
- * route's exported runner calls the same planner.
- */
-export function planLab(config, options, deps = {}) {
-    const lab = localBrowserDefaults(config);
-    const input = { dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true };
-    const result = planRoute(routeOf(config), lab, options, input, deps);
-    if (!result.ok)
-        return result;
-    // The manifest the CLI resolved (#455) enters the plan here and nowhere else; the routes read
-    // plan.lab for the run's status record and bundle.
-    const plan = options.lab === undefined ? result.plan : { ...result.plan, lab: options.lab };
-    return { ok: true, planned: { plan } };
-}
-function planRoute(route, lab, options, input, deps) {
-    switch (route) {
-        case "preview":
-            return planPreview(lab, options, input);
-        case "computer-use":
-            return planComputerUseLab(lab, {
-                ...input,
-                hasRunSession: deps.runSession !== undefined,
-                driving: callerDrivingOf(options),
-                ...(options.count === undefined ? {} : { countOverride: options.count }),
-                ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-            });
-        case "shared-world":
-            return planSharedWorldLab(lab, {
-                ...input,
-                hasRunSession: deps.runSession !== undefined,
-            });
-        case "terminal":
-            return planTerminalLab(lab, { ...input, hasCostProbe: deps.costProbe !== undefined });
-        case "scripted":
-            return planScriptedLab(lab, { ...input, injectedBrowser: injectedBrowser(deps) });
-    }
-}

package/dist/lab/preflight-probes.d.ts

@@ -1,3 +0,0 @@
-import type { LabPreflightResult, PreflightContext } from "./preflight.js";
-export declare function runPublicPreviewPreflight(ctx: PreflightContext): Promise<LabPreflightResult>;
-export declare function runSandboxLoopbackPreflight(ctx: PreflightContext): Promise<LabPreflightResult>;

package/dist/lab/preflight-result.d.ts

@@ -1,7 +0,0 @@
-import type { LabPreflightCheck, LabPreflightResult, PreflightContext } from "./preflight.js";
-export declare const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
-export declare function finalize(ctx: PreflightContext, args?: {
-    check?: LabPreflightCheck;
-}): LabPreflightResult;
-export declare function fail(ctx: PreflightContext, code: NonNullable<LabPreflightResult["error"]>["code"], message: string, checks: LabPreflightCheck[]): LabPreflightResult;
-export declare function digest(value: string): string;

package/dist/lab/preflight.d.ts

@@ -1,92 +0,0 @@
-import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
-import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
-import { type LabConfig } from "./types.js";
-import { LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
-import { type LabRoute } from "./plan.js";
-import { type LabResolveFailure } from "./discover.js";
-export type LabPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
-export interface LabPreflightCheck {
-    name: string;
-    ok: boolean;
-    message: string;
-}
-export interface LabPreflightTarget {
-    label: string;
-    kind: "subject.appUrl" | "actors[0].lanes[].target" | "subject.serve.url" | "subject.product.publicSurface";
-    targetDigest: string;
-    originDigest?: string;
-    loopback: boolean;
-    checked: boolean;
-    reachable?: boolean;
-    status: "not_checked" | "passed" | "failed" | "blocked";
-    statusCode?: number;
-    errorCode?: "HUMANISH_PREFLIGHT_TARGET_BLOCKED" | "HUMANISH_PREFLIGHT_TARGET_UNREACHABLE";
-    message: string;
-}
-interface LabPreflightSandbox {
-    created: boolean;
-    killed?: boolean;
-    /** The probe's server-side timeout, after which the provider kills it. */
-    timeoutMs?: number;
-    sandboxIdDigest?: string;
-    template?: string;
-}
-interface LabPreflightSpend {
-    e2bDesktop: boolean;
-    model: false;
-}
-export interface LabPreflightResult {
-    /** The separate budget for a future live run, never spend by preflight itself. */
-    analysis?: AutomaticAnalysisBudget;
-    schema: typeof LAB_PREFLIGHT_SCHEMA;
-    ok: boolean;
-    cwd: string;
-    lab: string;
-    labId?: string;
-    origin?: string;
-    path?: string;
-    route?: LabRoute;
-    reachability: LabPreflightReachabilityMode;
-    checks: LabPreflightCheck[];
-    targets: LabPreflightTarget[];
-    sandbox: LabPreflightSandbox;
-    spend: LabPreflightSpend;
-    warnings: string[];
-    error?: {
-        code: LabResolveFailure["error"]["code"] | "HUMANISH_LAB_PREFLIGHT_INVALID_OPTION" | "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY" | "HUMANISH_LAB_PREFLIGHT_ENV_MISSING" | "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED";
-        message: string;
-    };
-}
-interface LabPreflightHooks {
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    now?: () => number;
-    sleep?: (ms: number) => Promise<void>;
-}
-export interface RunLabPreflightOptions {
-    cwd: string;
-    lab: string;
-    reachability?: LabPreflightReachabilityMode;
-    timeoutMs?: number;
-    env?: NodeJS.ProcessEnv;
-    hooks?: LabPreflightHooks;
-}
-/** A preflight run's state; the probes in preflight-probes.ts read and extend it. */
-export interface PreflightContext {
-    cwd: string;
-    lab: string;
-    labId: string;
-    origin: string;
-    path: string;
-    config: LabConfig;
-    route: LabRoute;
-    reachability: LabPreflightReachabilityMode;
-    timeoutMs: number;
-    env: NodeJS.ProcessEnv;
-    hooks: LabPreflightHooks;
-    checks: LabPreflightCheck[];
-    targets: LabPreflightTarget[];
-    sandbox: LabPreflightSandbox;
-    warnings: string[];
-}
-export declare function runLabPreflight(options: RunLabPreflightOptions): Promise<LabPreflightResult>;
-export {};

package/dist/lab/route-inputs.d.ts

@@ -1,28 +0,0 @@
-import type { InternalRunLabOptions } from "../run-lab.js";
-import type { RunScorerProvenance } from "../run/bundle.js";
-import { type AdapterScorerModule } from "./adapter-scorer-loader.js";
-import type { LabDeps } from "./lab-deps.js";
-import type { LabEvent } from "./run-lab-events.js";
-import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
-import type { ScriptedRunInput } from "../routes/scripted/types.js";
-import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
-import type { TerminalRunInput } from "../routes/terminal/types.js";
-export declare function computerUseInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ComputerUseRunInput;
-export declare function scriptedInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ScriptedRunInput;
-export declare function terminalInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): TerminalRunInput;
-export declare function sharedWorldInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): SharedWorldRunInput;
-/** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
-export type LateScorer = Pick<InternalRunLabOptions, "scorer" | "scorerProvenance">;
-/** Narrows RunLabOptions.scorer to the context the route passes (adapter-scorer-loader.ts). */
-type NarrowScorer<S> = (scorer: AdapterScorerModule) => S;
-/**
- * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
- * caller had passed them up front. The rest of the input is the one the route's checks admitted.
- */
-export declare function withLateScorer<S, I extends {
-    scorer?: S;
-    scorerProvenance?: RunScorerProvenance;
-}>(input: I, late: LateScorer | undefined, narrow: NarrowScorer<S>): I;
-/** Reports a LabEvent to onEvent without waiting (normalizeRunLabOptions builds it). */
-type LabEmit = (event: LabEvent) => void;
-export {};

package/dist/lab/run-lab-options.d.ts

@@ -1,28 +0,0 @@
-import type { InternalRunLabOptions, LabOutcome, RunLabOptions } from "../run-lab.js";
-import { type LabRoute } from "./plan.js";
-import type { LabConfig } from "./types.js";
-import { type LabEvent } from "./run-lab-events.js";
-type Refusal = {
-    ok: false;
-    code: "HUMANISH_LAB_OPTION_UNSUPPORTED";
-    message: string;
-};
-type Normalized = {
-    ok: true;
-    /** The options the route reads: onEvent removed, env copied. */
-    options: InternalRunLabOptions;
-    /** Filled by onEvent failures while the run runs; runLab appends them to the result. */
-    warnings: string[];
-    /** Calls onEvent and never waits for it, or undefined without onEvent. The routes report through it. */
-    emit: ((event: LabEvent) => void) | undefined;
-};
-/** The refusal for a field a JavaScript caller passed that RunLabOptions no longer has. */
-export declare function removedOptionRefusal(options: RunLabOptions): Refusal | undefined;
-/**
- * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
- * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
- */
-export declare function normalizeRunLabOptions(config: LabConfig, route: LabRoute, options: InternalRunLabOptions): Normalized | Refusal;
-/** A refusal in the route's own result envelope, before any run exists. */
-export declare function optionRefusalOutcome(config: LabConfig, route: LabRoute, options: RunLabOptions, refusal: Refusal): LabOutcome;
-export {};

package/dist/lab/warnings.d.ts

@@ -1,2 +0,0 @@
-import type { LabConfig } from "./types.js";
-export declare function forwardDeclaredWarnings(config: LabConfig): string[];

package/dist/observer/static.d.ts

@@ -1,39 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-export declare const OBSERVER_STATIC_HOST = "127.0.0.1";
-export interface ObserverStaticHandlerOptions {
-    /** Directory served as the loopback root. Requests can never escape it. */
-    root: string;
-    /** File served for directory requests. Defaults to `index.html`. */
-    indexPath?: string;
-    /**
-     * When set, an exact `/` request returns a 302 to `/<redirectRootTo>` instead
-     * of serving a file. Used to land visitors on `observer/index.html` so the
-     * Observer's relative artifact links (`../run.json`, ...) resolve.
-     */
-    redirectRootTo?: string;
-}
-export interface ObserverStaticServeOptions extends ObserverStaticHandlerOptions {
-    /** TCP port to bind on 127.0.0.1. Defaults to an ephemeral port (0). */
-    port?: number;
-    /**
-     * Relative entry page (e.g. `observer/index.html`). Drives the returned
-     * `url` and the `/` -> entry redirect so callers open the page directly.
-     */
-    entryPath?: string;
-}
-export interface ObserverStaticServer {
-    url: string;
-    port: number;
-    host: string;
-    close(): Promise<void>;
-}
-export declare function observerStaticContentType(filePath: string): string;
-/**
- * Resolve, guard, and serve a single static request from `root`. Never throws:
- * any unexpected failure is reported as a 500 so the connection always closes.
- * Exported directly so the security guards can be unit-tested without binding a
- * socket.
- */
-export declare function respondToObserverStaticRequest(options: ObserverStaticHandlerOptions, request: Pick<IncomingMessage, "method" | "url">, response: ServerResponse): Promise<void>;
-export declare function createObserverStaticHandler(options: ObserverStaticHandlerOptions): (request: IncomingMessage, response: ServerResponse) => void;
-export declare function serveObserverStatic(options: ObserverStaticServeOptions): Promise<ObserverStaticServer>;