humanish 0.104.3 → 0.106.0

package/dist/lab/device-presets.js

@@ -0,0 +1,87 @@
+/**
+ * Named presets. Keys are the public vocabulary for `execution.desktop.device` and (later) a
+ * per-persona `device`. Values are copied verbatim from the in-house ui-sim screen tables;
+ * the per-line notes record where the two reference sims agree vs. diverge.
+ */
+export const DEVICE_PRESETS = {
+    // phone — both reference sims agree
+    mobile: { width: 414, height: 896, isMobile: true, deviceScaleFactor: 3 },
+    // small phone — both reference sims agree
+    "small-mobile": { width: 360, height: 740, isMobile: true, deviceScaleFactor: 3 },
+    // older narrow phone
+    "narrow-mobile": { width: 320, height: 700, isMobile: true, deviceScaleFactor: 2 },
+    // tablet — both reference sims agree
+    tablet: { width: 820, height: 1180, isMobile: false, deviceScaleFactor: 2 },
+    // laptop baseline (the in-house desktop screen; close to the 1440x960 dry-run surface in
+    // src/run/dry-run.ts)
+    desktop: { width: 1440, height: 950, isMobile: false, deviceScaleFactor: 1 },
+    // external monitor / most-common desktop resolution
+    wide: { width: 1920, height: 1080, isMobile: false, deviceScaleFactor: 1 },
+};
+/**
+ * Default device for a run that does not declare one. `desktop` (1440x950) is the median
+ * first-run laptop screen — the in-house desktop default, within 10px of the 1440x960 dry-run
+ * surface in src/run/dry-run.ts. `wide` (1920x1080), the most-common external monitor, is one
+ * keystroke away (`execution.desktop.device: wide`) but is deliberately not the default,
+ * because the median device a first-time user arrives on is a laptop, not a 1080p monitor.
+ */
+export const DEFAULT_DEVICE_PRESET = "desktop";
+/** The ordered list of preset names, for validation + help text. */
+export const DEVICE_PRESET_NAMES = Object.keys(DEVICE_PRESETS);
+export function isDevicePresetName(value) {
+    return typeof value === "string" && value in DEVICE_PRESETS;
+}
+/** Resolve a preset name (or undefined) to its preset, falling back to the default. */
+export function resolveDevicePreset(name) {
+    return DEVICE_PRESETS[name ?? DEFAULT_DEVICE_PRESET];
+}
+/**
+ * The narrowest browser WINDOW Chrome/Chromium will render on the E2B desktop. Chrome refuses to
+ * make its window narrower than this (~500 CSS px observed: a 414-wide X screen produced a 500-wide
+ * window that OVERFLOWED it, clipping the right edge of the page off-screen). So the physically
+ * RENDERED screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
+ * narrow-mobile 320) gets a 500-wide screen the window fits exactly — no clip. The device PRESET keeps
+ * its true identity (isMobile, nominal width) for the persona prompt + metadata; only the rendered
+ * screen is floored. True sub-500 CSS-viewport rendering (page laid out at 414 regardless of window
+ * width, via CDP device-metric emulation) is the separate #221 upgrade.
+ */
+export const MIN_DESKTOP_RENDER_WIDTH = 500;
+/** Floor a screen resolution's WIDTH to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
+export function floorRenderResolution(resolution) {
+    return [Math.max(resolution[0], MIN_DESKTOP_RENDER_WIDTH), resolution[1]];
+}
+/**
+ * Resolve a participant's device + rendered resolution (most-specific wins, exactly as the
+ * single-participant path always has): a raw execution.desktop.resolution escape hatch (only legal
+ * when no roster entry sets a device — XOR enforced at parse) → the participant's named device → the run-wide
+ * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
+ * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry. The rendered
+ * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);
+ * `preset` keeps the declared device identity (a mobile preset stays 414/isMobile for the prompt).
+ */
+export function resolveParticipantDevice(config, 
+/** The device the participant's roster entry names, if any. */
+device) {
+    const rawResolution = config.execution?.desktop?.resolution;
+    if (device === undefined && rawResolution) {
+        const preset = {
+            width: rawResolution[0],
+            height: rawResolution[1],
+            isMobile: false,
+            deviceScaleFactor: 1,
+        };
+        return {
+            name: "custom",
+            preset,
+            resolution: floorRenderResolution([rawResolution[0], rawResolution[1]]),
+        };
+    }
+    const candidate = device ?? config.execution?.desktop?.device;
+    const presetName = isDevicePresetName(candidate) ? candidate : DEFAULT_DEVICE_PRESET;
+    const preset = resolveDevicePreset(presetName);
+    return {
+        name: presetName,
+        preset,
+        resolution: floorRenderResolution([preset.width, preset.height]),
+    };
+}

package/dist/lab/discover.d.ts

@@ -0,0 +1,65 @@
+import type { ActorPersonaRef } from "../actors/contract.js";
+import { type LabConfig } from "./types.js";
+declare const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
+declare const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
+type LabOrigin = "committed" | "ignored" | "explicit";
+interface ResolvedLabConfig {
+    config: LabConfig;
+    origin: LabOrigin;
+    path: string;
+    warnings: string[];
+}
+export interface LabResolveFailure {
+    ok: false;
+    cwd: string;
+    lab: string;
+    error: {
+        code: "HUMANISH_LAB_NOT_FOUND" | "HUMANISH_LAB_INVALID";
+        message: string;
+    };
+    warnings: string[];
+}
+export type LabResolveResult = ({
+    ok: true;
+} & ResolvedLabConfig) | LabResolveFailure;
+export interface LabListEntry {
+    id: string;
+    source: LabConfig["subject"]["source"];
+    origin: LabOrigin;
+    path: string;
+    title?: string;
+    /**
+     * The manifest's own first sentence. The list is where someone decides which study to open, and a
+     * list of names cannot answer "what is this one" for a project with twenty labs in it — the
+     * stakeholder feedback that added this was, verbatim, "so i know wtf they are".
+     */
+    description?: string;
+}
+export interface LabListResult {
+    schema: typeof LAB_LIST_SCHEMA;
+    ok: true;
+    cwd: string;
+    labs: LabListEntry[];
+    warnings: string[];
+}
+export interface LabInspectResult {
+    /** Persona context only, before route instructions and runtime grants. */
+    personas?: Array<{
+        id: string;
+        resolved: boolean;
+        brief?: ActorPersonaRef["brief"];
+    }>;
+    schema: typeof LAB_INSPECT_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    lab: string;
+    config?: LabConfig;
+    origin?: LabOrigin;
+    path?: string;
+    error?: LabResolveFailure["error"];
+    warnings: string[];
+}
+export declare function resolveLabManifest(cwd: string, lab: string): Promise<LabResolveResult>;
+export declare function listLabManifests(cwd: string): Promise<LabListResult>;
+export declare function inspectLabManifest(cwd: string, lab: string): Promise<LabInspectResult>;
+export {};

package/dist/lab/discover.js

@@ -0,0 +1,422 @@
+import { labPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
+import { personaBrief, PersonaConfigError } from "./persona.js";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { parseLabConfig } from "./config.js";
+import {} from "./types.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
+const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
+const committedLabsDir = path.join("humanish", "labs");
+const ignoredLabsDirs = [
+    path.join(".humanish", "labs"),
+    path.join(".humanish", "local", "labs"),
+];
+export async function resolveLabManifest(cwd, lab) {
+    const resolvedCwd = path.resolve(cwd);
+    const warnings = [];
+    const projectRoot = await bindProjectRoot(resolvedCwd);
+    if (!projectRoot) {
+        return invalidLab({ cwd: resolvedCwd, lab, warnings }, "Project root failed containment validation.");
+    }
+    if (labLooksLikePath(lab)) {
+        const requestedPath = path.resolve(resolvedCwd, lab);
+        const read = await readExplicitManifest(projectRoot, requestedPath);
+        if (read.status === "missing") {
+            return labNotFound(resolvedCwd, lab, warnings);
+        }
+        if (read.status === "unsafe") {
+            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+        }
+        return parseResolvedLab({
+            cwd: resolvedCwd,
+            lab,
+            origin: "explicit",
+            path: requestedPath,
+            warnings,
+            contents: read.contents,
+        });
+    }
+    const candidates = [
+        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yaml`) },
+        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yml`) },
+        ...ignoredLabsDirs.flatMap((dir) => [
+            { origin: "ignored", relativePath: path.join(dir, `${lab}.yaml`) },
+            { origin: "ignored", relativePath: path.join(dir, `${lab}.yml`) },
+        ]),
+    ];
+    for (const candidate of candidates) {
+        const requestedPath = path.join(resolvedCwd, candidate.relativePath);
+        const read = await readManagedManifest(projectRoot, candidate.relativePath);
+        if (read.status === "missing") {
+            continue;
+        }
+        if (read.status === "unsafe") {
+            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+        }
+        return parseResolvedLab({
+            cwd: resolvedCwd,
+            lab,
+            origin: candidate.origin,
+            path: requestedPath,
+            warnings,
+            contents: read.contents,
+        });
+    }
+    return labNotFound(resolvedCwd, lab, warnings);
+}
+export async function listLabManifests(cwd) {
+    const resolvedCwd = path.resolve(cwd);
+    const warnings = [];
+    const labs = new Map();
+    const projectRoot = await bindProjectRoot(resolvedCwd);
+    if (!projectRoot) {
+        return {
+            schema: LAB_LIST_SCHEMA,
+            ok: true,
+            cwd: resolvedCwd,
+            labs: [],
+            warnings: ["Project root failed containment validation; managed lab manifests were skipped."],
+        };
+    }
+    const dirs = [
+        { origin: "committed", relativeDir: committedLabsDir },
+        ...ignoredLabsDirs.map((relativeDir) => ({ origin: "ignored", relativeDir })),
+    ];
+    for (const entry of dirs) {
+        const directory = await bindManagedDirectory(projectRoot, entry.relativeDir);
+        if (directory.status === "missing") {
+            continue;
+        }
+        if (directory.status === "unsafe") {
+            warnings.push(`${entry.relativeDir}: ${directory.message}`);
+            continue;
+        }
+        let names;
+        try {
+            names = await readdir(directory.binding.physicalPath);
+            await assertManagedDirectoryBinding(projectRoot, entry.relativeDir, directory.binding);
+        }
+        catch {
+            warnings.push(`${entry.relativeDir}: unsafe managed lab directory; skipped.`);
+            continue;
+        }
+        for (const name of names.filter((value) => value.endsWith(".yaml") || value.endsWith(".yml"))) {
+            let relativePath;
+            try {
+                assertSafeOutputPathSegment(name, "Lab manifest name");
+                relativePath = path.join(entry.relativeDir, name);
+            }
+            catch {
+                warnings.push(`${entry.relativeDir}: unsafe lab manifest name; skipped.`);
+                continue;
+            }
+            const requestedPath = path.join(resolvedCwd, relativePath);
+            const read = await readManagedManifest(projectRoot, relativePath);
+            if (read.status !== "ok") {
+                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${read.status === "unsafe" ? read.message : "manifest changed while it was listed; skipped."}`);
+                continue;
+            }
+            const parsed = parseResolvedLab({
+                cwd: resolvedCwd,
+                lab: name.replace(/\.(?:ya?ml)$/i, ""),
+                origin: entry.origin,
+                path: requestedPath,
+                warnings: [],
+                contents: read.contents,
+            });
+            if (!parsed.ok) {
+                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${parsed.error.message}`);
+                continue;
+            }
+            const key = `${parsed.config.id}:${entry.origin}:${relativeToCwd(resolvedCwd, requestedPath)}`;
+            labs.set(key, {
+                id: parsed.config.id,
+                source: parsed.config.subject.source,
+                origin: entry.origin,
+                path: relativeToCwd(resolvedCwd, requestedPath),
+                ...(parsed.config.title ? { title: parsed.config.title } : {}),
+                ...(typeof parsed.config.description === "string" &&
+                    parsed.config.description.trim().length > 0
+                    ? { description: parsed.config.description.trim() }
+                    : {}),
+            });
+        }
+    }
+    return {
+        schema: LAB_LIST_SCHEMA,
+        ok: true,
+        cwd: resolvedCwd,
+        labs: [...labs.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
+        warnings,
+    };
+}
+export async function inspectLabManifest(cwd, lab) {
+    const resolved = await resolveLabManifest(cwd, lab);
+    if (!resolved.ok) {
+        return {
+            schema: LAB_INSPECT_SCHEMA,
+            ok: false,
+            cwd: resolved.cwd,
+            lab,
+            error: resolved.error,
+            warnings: resolved.warnings,
+        };
+    }
+    let personaResolution;
+    try {
+        personaResolution = await resolveCommittedPersonasForCwd(cwd, labPersonaIds(resolved.config));
+    }
+    catch (error) {
+        if (!(error instanceof PersonaConfigError))
+            throw error;
+        return {
+            schema: LAB_INSPECT_SCHEMA,
+            ok: false,
+            cwd: path.resolve(cwd),
+            lab,
+            error: { code: "HUMANISH_LAB_INVALID", message: error.message },
+            warnings: resolved.warnings,
+        };
+    }
+    return {
+        schema: LAB_INSPECT_SCHEMA,
+        personas: labPersonaIds(resolved.config).map((id) => {
+            const persona = personaResolution.personas.get(id);
+            return { id, resolved: !!persona, ...(persona ? { brief: personaBrief(persona) } : {}) };
+        }),
+        ok: true,
+        cwd: path.resolve(cwd),
+        lab,
+        config: resolved.config,
+        origin: resolved.origin,
+        path: resolved.path,
+        warnings: [...resolved.warnings, ...personaResolution.warnings],
+    };
+}
+function parseResolvedLab(args) {
+    let raw;
+    try {
+        raw = parse(args.contents);
+    }
+    catch (error) {
+        return invalidLab(args, error instanceof Error ? error.message : "Lab YAML could not be parsed.");
+    }
+    const parsed = parseLabConfig(raw);
+    if (!parsed.ok) {
+        return invalidLab(args, parsed.error.message);
+    }
+    const warnings = [...args.warnings, ...parsed.warnings];
+    if (args.path.endsWith(".yml")) {
+        warnings.push("Prefer .yaml for humanish-authored lab source; .yml is accepted for compatibility only.");
+    }
+    return {
+        ok: true,
+        config: parsed.config,
+        origin: args.origin,
+        path: relativeToCwd(args.cwd, args.path),
+        warnings,
+    };
+}
+async function bindProjectRoot(cwd) {
+    try {
+        const lexical = await lstat(cwd);
+        if (!lexical.isDirectory() && !lexical.isSymbolicLink()) {
+            return null;
+        }
+        return await prepareSelectedOutputDirectory(path.dirname(cwd), cwd);
+    }
+    catch {
+        return null;
+    }
+}
+async function readManagedManifest(projectRoot, relativePath) {
+    const inspected = await inspectManagedPath(projectRoot, relativePath, "file");
+    if (inspected.status !== "ok") {
+        return inspected;
+    }
+    const contents = await readContainedRegularFile(projectRoot, relativePath.replace(/\\/g, "/"));
+    if (!contents) {
+        return {
+            status: "unsafe",
+            message: "Managed lab manifest changed or failed containment validation.",
+        };
+    }
+    return { status: "ok", contents: contents.toString("utf8") };
+}
+async function readExplicitManifest(projectRoot, requestedPath) {
+    try {
+        await assertPreparedSelectedOutputDirectory(projectRoot);
+        try {
+            await lstat(requestedPath);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return { status: "missing" };
+            }
+            throw error;
+        }
+        const physicalPath = await realpath(requestedPath);
+        const before = await lstat(physicalPath, { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
+            return {
+                status: "unsafe",
+                message: "Explicit lab manifest must resolve to a single-link regular file.",
+            };
+        }
+        const handle = await open(physicalPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const opened = await handle.stat({ bigint: true });
+            if (!opened.isFile() ||
+                opened.nlink !== 1n ||
+                opened.dev !== before.dev ||
+                opened.ino !== before.ino) {
+                return {
+                    status: "unsafe",
+                    message: "Explicit lab manifest changed before it could be read safely.",
+                };
+            }
+            const contents = await handle.readFile();
+            const [currentPhysicalPath, after] = await Promise.all([
+                realpath(requestedPath),
+                lstat(physicalPath, { bigint: true }),
+            ]);
+            await assertPreparedSelectedOutputDirectory(projectRoot);
+            if (currentPhysicalPath !== physicalPath ||
+                !after.isFile() ||
+                after.isSymbolicLink() ||
+                after.nlink !== 1n ||
+                after.dev !== before.dev ||
+                after.ino !== before.ino) {
+                return {
+                    status: "unsafe",
+                    message: "Explicit lab manifest changed while it was being read.",
+                };
+            }
+            return { status: "ok", contents: contents.toString("utf8") };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return { status: "unsafe", message: "Explicit lab manifest failed containment validation." };
+    }
+}
+async function bindManagedDirectory(projectRoot, relativePath) {
+    const inspected = await inspectManagedPath(projectRoot, relativePath, "directory");
+    if (inspected.status !== "ok") {
+        return inspected;
+    }
+    return {
+        status: "ok",
+        binding: {
+            birthtimeNs: inspected.birthtimeNs,
+            dev: inspected.dev,
+            ino: inspected.ino,
+            physicalPath: inspected.physicalPath,
+        },
+    };
+}
+async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
+    try {
+        await assertPreparedSelectedOutputDirectory(projectRoot);
+        const segments = relativePath.replace(/\\/g, "/").split("/");
+        let current = projectRoot.physicalPath;
+        for (const [index, segment] of segments.entries()) {
+            assertSafeOutputPathSegment(segment, "Managed lab path segment");
+            current = path.join(current, segment);
+            let stats;
+            try {
+                stats = await lstat(current, { bigint: true });
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "ENOENT") {
+                    return { status: "missing" };
+                }
+                throw error;
+            }
+            const leaf = index === segments.length - 1;
+            if (stats.isSymbolicLink()) {
+                return { status: "unsafe", message: "Managed lab paths must not contain symbolic links." };
+            }
+            if (!leaf && !stats.isDirectory()) {
+                return { status: "unsafe", message: "Managed lab path parents must be directories." };
+            }
+            if (leaf && expectedKind === "directory" && !stats.isDirectory()) {
+                return { status: "unsafe", message: "Managed lab directory has an unsafe file type." };
+            }
+            if (leaf && expectedKind === "file" && (!stats.isFile() || stats.nlink !== 1n)) {
+                return {
+                    status: "unsafe",
+                    message: "Managed lab manifest must be a single-link regular file.",
+                };
+            }
+            if (leaf) {
+                await assertPreparedSelectedOutputDirectory(projectRoot);
+                return {
+                    status: "ok",
+                    birthtimeNs: stats.birthtimeNs,
+                    dev: stats.dev,
+                    ino: stats.ino,
+                    physicalPath: current,
+                };
+            }
+        }
+    }
+    catch {
+        return { status: "unsafe", message: "Managed lab path failed containment validation." };
+    }
+    return { status: "missing" };
+}
+async function assertManagedDirectoryBinding(projectRoot, relativePath, binding) {
+    await assertPreparedSelectedOutputDirectory(projectRoot);
+    const current = await inspectManagedPath(projectRoot, relativePath, "directory");
+    if (current.status !== "ok" ||
+        current.physicalPath !== binding.physicalPath ||
+        current.birthtimeNs !== binding.birthtimeNs ||
+        current.dev !== binding.dev ||
+        current.ino !== binding.ino) {
+        throw new Error("Managed lab directory identity changed after it was bound.");
+    }
+}
+function invalidLab(args, message) {
+    return {
+        ok: false,
+        cwd: args.cwd,
+        lab: args.lab,
+        error: {
+            code: "HUMANISH_LAB_INVALID",
+            message,
+        },
+        warnings: args.warnings,
+    };
+}
+function labNotFound(cwd, lab, warnings) {
+    return {
+        ok: false,
+        cwd,
+        lab,
+        error: {
+            code: "HUMANISH_LAB_NOT_FOUND",
+            message: `Lab not found: ${lab}. Look in humanish/labs/ or pass a .yaml path.`,
+        },
+        warnings,
+    };
+}
+function labLooksLikePath(lab) {
+    return (lab.endsWith(".yaml") ||
+        lab.endsWith(".yml") ||
+        lab.includes("/") ||
+        lab.includes("\\") ||
+        lab.startsWith("."));
+}
+function relativeToCwd(cwd, filePath) {
+    const relative = path.relative(cwd, filePath);
+    return relative && !relative.startsWith("..") ? relative : filePath;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/lab/doctor.d.ts

@@ -0,0 +1,39 @@
+import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
+import type { LabConfig } from "./types.js";
+import type { LabRoute } from "./plan.js";
+import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
+import type { DoctorResult } from "../cli/doctor.js";
+type Check = DoctorResult["checks"][number];
+/** Read-only Codex account readiness. An unadmitted CLI also reports the release it found. */
+type CodexReadiness = {
+    ready: boolean;
+    errorCode: string | null;
+    detectedCliVersion?: string;
+};
+/** Shared read-only Codex account check for local participants in doctor and the TUI. */
+export declare function localCodexParticipantCheck(args: {
+    env: NodeJS.ProcessEnv;
+    readiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
+}): Promise<Check>;
+interface LabSetupCheckArgs {
+    cwd: string;
+    lab: string;
+    env: NodeJS.ProcessEnv;
+    agents: DetectedLocalAgent[];
+    keyPresent: (name: string) => boolean;
+    /** Internal read-only qualification seam; never a participant/model request. */
+    localRuntimeReadiness?: () => Promise<LocalRuntimeStatus>;
+    codexAnalysisReadiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
+}
+/** Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network. */
+export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
+    desktop: boolean;
+    keys: string[];
+    checks: Check[];
+}>;
+/** Required participant provider keys, shared by doctor and the TUI. Optional analysis is separate. */
+export declare function labKeyRequirements(config: LabConfig, route: LabRoute, dryRun: boolean, keyPresent: (name: string) => boolean): {
+    desktop: boolean;
+    keys: string[];
+};
+export {};