humanish 0.104.3 → 0.106.0

package/dist/lab/doctor.js

@@ -0,0 +1,233 @@
+import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
+import { localRuntimeStatus } from "../substrates/local/runtime.js";
+import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { externalCatchHealthy } from "../comms/sandbox-catch.js";
+import { receivingRequiredKey } from "../comms/setup.js";
+import { codexVersionRecovery } from "../actors/codex/qualified-versions.js";
+/** The account check doctor and the TUI share; the version probe runs only for an unadmitted CLI. */
+async function codexAccountReadiness(env) {
+    const readiness = await (await import("../analysis/restricted-codex.js")).checkRestrictedCodexAnalysisReadiness({ timeoutMs: 5000 }, { env });
+    if (readiness.errorCode !== "codex_unsupported_version")
+        return readiness;
+    const { detectRestrictedCodexCliVersion } = await import("../actors/codex/restricted-session.js");
+    const detected = await detectRestrictedCodexCliVersion({ timeoutMs: 5000 }, { env }).catch(() => undefined);
+    // An admitted release here means app-server reported a different one; name what --version says.
+    const version = detected?.cliVersion ?? detected?.detectedVersion;
+    return version === undefined ? readiness : { ...readiness, detectedCliVersion: version };
+}
+/** What to do about a Codex readiness failure; an unadmitted CLI gets its exact install command. */
+function codexRecovery(readiness, fallback) {
+    return readiness.errorCode === "codex_unsupported_version"
+        ? codexVersionRecovery(readiness.detectedCliVersion)
+        : fallback;
+}
+/** Shared read-only Codex account check for local participants in doctor and the TUI. */
+export async function localCodexParticipantCheck(args) {
+    const readiness = await (args.readiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
+    return {
+        name: "local participant authentication",
+        ok: readiness.ready,
+        message: readiness.ready
+            ? "Qualified Codex CLI and ChatGPT login are ready for restricted local browser participants. No E2B or model API key is required; inference is remote, and model access and account quota remain untested."
+            : `Local Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Install the supported Codex CLI version and sign in with a ChatGPT account.")} No API fallback is used.`,
+    };
+}
+/** Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network. */
+export async function labSetupChecks(args) {
+    const { resolveLabManifest } = await import("./discover.js");
+    const { resolveLabDryRun, routeOf } = await import("./plan.js");
+    const resolved = await resolveLabManifest(args.cwd, args.lab);
+    if (!resolved.ok)
+        return {
+            desktop: false,
+            keys: [],
+            checks: [{ name: "lab", ok: false, message: resolved.error.message }],
+        };
+    const config = resolved.config, route = routeOf(config);
+    const dryRun = resolveLabDryRun(config, undefined, true) === true;
+    const checks = [
+        {
+            name: "lab route",
+            ok: true,
+            message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
+        },
+    ];
+    if (dryRun)
+        return { desktop: false, keys: [], checks };
+    const unsupported = unsupportedCliRoute(config, route);
+    if (unsupported)
+        return {
+            desktop: false,
+            keys: [],
+            checks: [...checks, { name: "live route", ok: false, message: unsupported }],
+        };
+    const { desktop, keys } = labKeyRequirements(config, route, false, args.keyPresent);
+    const local = isLocalBrowserLab(config);
+    // One account check, shared by the local participant row and the Codex analysis row.
+    let accountReadiness;
+    const checkAccount = () => (accountReadiness ??= (args.codexAnalysisReadiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" })));
+    if (local)
+        checks.push(...(await localBrowserChecks(config, args)));
+    if (config.comms?.email?.kind === "real")
+        checks.push(await realEmailCheck(config.comms.email.connection, keys, args));
+    checks.push(...(await participantChecks(config, route, keys, local, args, checkAccount)));
+    if (route === "scripted")
+        checks.push(await scriptedBrowserCheck());
+    checks.push(...subjectEnvChecks(config, args));
+    const analysis = automaticAnalysisBudget(config.review?.analysis, route);
+    if (analysis)
+        checks.push(await analysisCheck(analysis, args, checkAccount));
+    checks.push(checkScope(analysis));
+    return { desktop, keys, checks };
+}
+/** A local browser study's runtime and, with an external catch, its captured inbox. */
+async function localBrowserChecks(config, args) {
+    const checks = [];
+    const runtime = await (args.localRuntimeReadiness ??
+        (() => localRuntimeStatus({
+            env: args.env,
+            media: config.execution?.desktop?.media !== undefined ||
+                config.execution?.desktop?.recording !== undefined,
+        })))();
+    checks.push({ name: "local browser runtime", ok: runtime.ok, message: runtime.message });
+    const email = config.comms?.email;
+    if (email?.kind === "fake" && email.external) {
+        const healthy = await externalCatchHealthy(email.external, { timeoutMs: 5000 });
+        checks.push({
+            name: "local captured inbox",
+            ok: healthy,
+            message: healthy
+                ? "Recipient inbox routes are ready. Point your app's email sends at this catch; delivery remains untested. No mailbox-provider credentials are needed, and this does not receive arbitrary internet mail."
+                : "Captured inbox is unavailable or outdated. Start or upgrade and restart humanish comms catch, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.",
+        });
+    }
+    return checks;
+}
+/** The saved real email connection. Adds the key it needs to `keys`. */
+async function realEmailCheck(connection, keys, args) {
+    const name = await receivingRequiredKey(args.cwd, connection);
+    if (name)
+        keys.push(name);
+    return {
+        name: "real email connection",
+        ok: name !== null && args.keyPresent(name),
+        message: name === null
+            ? "The selected email connection is missing or invalid. Open Connections in the TUI."
+            : !args.keyPresent(name)
+                ? `Missing ${name} for the selected email connection. Provide it through process env or --env-file. Authentication has not been checked.`
+                : "Fresh hosted inbox per participant. Local presence only; run humanish comms check --online to authenticate. Provider permissions/capacity and delivery remain untested.",
+    };
+}
+/** How the participant authenticates: the terminal model key, or a local agent's login. */
+async function participantChecks(config, route, keys, local, args, checkAccount) {
+    if (route === "terminal") {
+        const key = keys.find((name) => name !== "E2B_API_KEY");
+        return [
+            {
+                name: "terminal model authentication",
+                ok: args.keyPresent(key),
+                message: "The in-sandbox Codex runtime needs CODEX_API_KEY or OPENAI_API_KEY. Your host's Codex login is not forwarded; credential placement follows execution.runtimeAuth.",
+            },
+        ];
+    }
+    if ((route !== "computer-use" && route !== "shared-world") ||
+        config.actors[0]?.type !== "local-agent")
+        return [];
+    const choice = config.actors[0]?.localAgent ?? "codex";
+    const agent = args.agents.find((entry) => entry.id === choice);
+    if (local)
+        return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
+    return [
+        {
+            name: "local participant authentication",
+            ok: agent?.authStatus === "authenticated",
+            message: agent?.authStatus === "authenticated"
+                ? `${agent.label} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`
+                : agent
+                    ? `${agent.label} ${agent.authStatus === "unauthenticated" ? "reports not signed in" : "authentication could not be checked"}. Run \`${choice === "codex" ? "codex login status" : "claude auth status"}\`; sign in or update the CLI before running.`
+                    : `${choice} is not on this process's PATH. Install and sign in to that CLI, or choose openai-computer-use with OPENAI_API_KEY.`,
+        },
+    ];
+}
+/** The local Chrome/Chromium the scripted-browser route drives. */
+async function scriptedBrowserCheck() {
+    const { resolveBrowserCommand } = await import("../actors/scripted-browser/browser-command.js");
+    return {
+        name: "scripted browser",
+        ok: !!(await resolveBrowserCommand()),
+        message: "Scripted-browser uses local Chrome/Chromium and no participant model. Install Chrome/Chromium or set HUMANISH_BROWSER_COMMAND; a clone subject additionally needs E2B.",
+    };
+}
+/** One row per declared subject env name: present or missing, never the value. */
+function subjectEnvChecks(config, args) {
+    return (config.subject.env ?? []).map((name) => ({
+        name: `subject env ${name}`,
+        ok: !!args.env[name]?.trim() || args.keyPresent(name),
+        message: args.env[name]?.trim() || args.keyPresent(name)
+            ? "present; value not shown"
+            : "missing declared subject environment variable; provide it with --env-file",
+    }));
+}
+/** The post-run analysis: the Codex account, or the OpenAI key and the admission estimate limit. */
+async function analysisCheck(analysis, args, checkAccount) {
+    if (analysis.provider === "codex") {
+        const readiness = await checkAccount();
+        const recovery = readiness.errorCode === "codex_unsupported_platform"
+            ? "Use Linux x64 or the Apple Silicon Mac with a supported Codex CLI, or explicitly select provider: openai with an API key."
+            : readiness.errorCode === "codex_busy"
+                ? "Another restricted Codex analyst or setup check is active in this process. Wait for it to finish, then retry."
+                : codexRecovery(readiness, "Install the qualified CLI and sign in with a ChatGPT account.");
+        return {
+            name: "post-run analysis",
+            ok: readiness.ready,
+            message: readiness.ready
+                ? "Qualified Codex CLI and ChatGPT account login are ready for a separate restricted analyst. Analysis sends selected evidence to remote inference; model access and account allowance remain untested. Dollar cost and output-token ceilings are unavailable."
+                : `Codex account analysis is unavailable (${readiness.errorCode ?? "codex_unavailable"}). ${recovery} No API fallback is used; participant readiness is independent.`,
+        };
+    }
+    return {
+        name: "post-run analysis",
+        ok: true,
+        message: args.keyPresent("OPENAI_API_KEY")
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. Its $${analysis.maxCostUsd} admission estimate limit may decline larger studies before dispatch; it is not a provider billing cap. Participant readiness is independent.`
+            : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
+    };
+}
+/** What doctor checked and what it did not. */
+function checkScope(analysis) {
+    return {
+        name: "check scope",
+        ok: true,
+        message: analysis?.provider === "codex"
+            ? "The Codex setup check inspects local login and configuration without a model turn or participant resources. Remote account validity, model access, quota and target reachability remain untested; CLI startup may use the network."
+            : "Local setup only. Provider credentials are not validated, model access/quota and target reachability are untested, and no paid resources were created.",
+    };
+}
+/** Required participant provider keys, shared by doctor and the TUI. Optional analysis is separate. */
+export function labKeyRequirements(config, route, dryRun, keyPresent) {
+    if (dryRun || unsupportedCliRoute(config, route))
+        return { desktop: false, keys: [] };
+    // This flag controls the hosted desktop SDK check as well as its API key.
+    const desktop = !isLocalBrowserLab(config) &&
+        (route === "computer-use" ||
+            route === "terminal" ||
+            route === "shared-world" ||
+            (route === "scripted" && config.subject.source === "clone"));
+    const keys = desktop ? ["E2B_API_KEY"] : [];
+    const openaiBrain = config.actors[0]?.type !== "local-agent";
+    if (route === "terminal")
+        keys.push(keyPresent("CODEX_API_KEY") ? "CODEX_API_KEY" : "OPENAI_API_KEY");
+    // Shared world's external-public plane reads the host's lobby code with the OpenAI API,
+    // whatever brain drives the participants (routes/shared-world/plan.ts).
+    else if ((route === "computer-use" && openaiBrain) ||
+        (route === "shared-world" && (openaiBrain || config.subject.source === "app-url")))
+        keys.push("OPENAI_API_KEY");
+    return { desktop, keys };
+}
+function unsupportedCliRoute(config, route) {
+    if (config.subject.source === "local-app")
+        return "local-app needs a caller-supplied executor and provider through the library API; the plain CLI cannot run it.";
+    if (route === "preview")
+        return "This route only creates synthetic evidence. Use first-run in dry-run mode or a supported live lab.";
+    return undefined;
+}

package/dist/lab/init-paths.d.ts

@@ -0,0 +1,5 @@
+import { type PreparedSelectedOutputDirectory } from "../run/contained-output.js";
+import type { InitResult } from "./init.js";
+export declare function validateInitProjectPaths(cwd: string): Promise<InitResult["error"] | null>;
+export declare function readTextIfExists(projectRoot: PreparedSelectedOutputDirectory, relativePath: string): Promise<string | null>;
+export declare function pathExists(projectRoot: PreparedSelectedOutputDirectory, relativePath: string): Promise<boolean>;

package/dist/lab/init-paths.js

@@ -0,0 +1,89 @@
+// Path checks for `humanish init`: every file and directory init may write (inside the project,
+// the expected kind, no symbolic links or hardlinked files), and the contained reads init makes of
+// existing files. The target cwd check is validateCwd in run/project.ts.
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { runtimeDirectories, starterFiles } from "./init-templates.js";
+import { assertPreparedSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { isPathInside } from "../run/paths.js";
+import { isNodeError } from "../run/type-guards.js";
+export async function validateInitProjectPaths(cwd) {
+    const targets = [
+        ...starterFiles.map((file) => ({ path: file.path, kind: "file" })),
+        ...runtimeDirectories.map((directory) => ({
+            path: directory.path,
+            kind: "directory",
+        })),
+        { path: ".gitignore", kind: "file" },
+        { path: "package.json", kind: "file" },
+    ];
+    for (const targetSpec of targets) {
+        const relativePath = targetSpec.path;
+        const target = path.resolve(cwd, relativePath);
+        if (!isPathInside(cwd, target)) {
+            return unsafeProjectPath(relativePath);
+        }
+        const parts = path.relative(cwd, target).split(path.sep).filter(Boolean);
+        let current = cwd;
+        for (const [index, part] of parts.entries()) {
+            current = path.join(current, part);
+            try {
+                const stats = await lstat(current);
+                const isLeaf = index === parts.length - 1;
+                if (stats.isSymbolicLink() ||
+                    (!isLeaf && !stats.isDirectory()) ||
+                    (isLeaf && targetSpec.kind === "file" && (!stats.isFile() || stats.nlink > 1)) ||
+                    (isLeaf && targetSpec.kind === "directory" && !stats.isDirectory())) {
+                    return unsafeProjectPath(relativePath);
+                }
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "ENOENT") {
+                    break;
+                }
+                return unsafeProjectPath(relativePath);
+            }
+        }
+    }
+    return null;
+}
+function unsafeProjectPath(relativePath) {
+    return {
+        code: "HUMANISH_UNSAFE_PROJECT_PATH",
+        message: `Init target must stay inside the project, use the expected regular-file or directory kind, and not traverse symbolic links or hardlinked files: ${relativePath}`,
+    };
+}
+export async function readTextIfExists(projectRoot, relativePath) {
+    const bytes = await readContainedRegularFile(projectRoot, relativePath);
+    if (bytes !== null) {
+        return bytes.toString("utf8");
+    }
+    const target = path.join(projectRoot.physicalPath, relativePath);
+    try {
+        await lstat(target);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    throw new Error(unsafeProjectPath(relativePath).message);
+}
+export async function pathExists(projectRoot, relativePath) {
+    await assertPreparedSelectedOutputDirectory(projectRoot);
+    const filePath = path.join(projectRoot.physicalPath, relativePath);
+    try {
+        const stats = await lstat(filePath);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new Error(unsafeProjectPath(relativePath).message);
+        }
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}

package/dist/lab/init-plan.d.ts

@@ -0,0 +1,20 @@
+import type { PreparedSelectedOutputDirectory } from "../run/contained-output.js";
+import type { InitChange, InitResult } from "./init.js";
+export interface PlannedWrite {
+    absolutePath: string;
+    relativePath: string;
+    contents: string;
+    target: InitChange["target"];
+}
+interface PackagePlan {
+    write?: PlannedWrite;
+    change: InitChange;
+    warnings: string[];
+    error?: InitResult["error"];
+}
+export declare function planGitignore(projectRoot: PreparedSelectedOutputDirectory, cwd: string): Promise<{
+    write?: PlannedWrite;
+    change: InitChange;
+}>;
+export declare function planPackageJson(projectRoot: PreparedSelectedOutputDirectory, cwd: string): Promise<PackagePlan>;
+export {};

package/dist/lab/init-plan.js

@@ -0,0 +1,163 @@
+// The edits `humanish init` plans for files the project already owns: .gitignore gains the runtime
+// and env lines it lacks, and package.json gains the humanish scripts it lacks. Nothing is written
+// here; runInit applies the plan.
+import path from "node:path";
+import { humanishScripts } from "./init-templates.js";
+import { readTextIfExists } from "./init-paths.js";
+export async function planGitignore(projectRoot, cwd) {
+    const relativePath = ".gitignore";
+    const absolutePath = path.join(cwd, relativePath);
+    const existing = await readTextIfExists(projectRoot, relativePath);
+    const currentLines = existing?.split(/\r?\n/) ?? [];
+    const envIndex = currentLines.lastIndexOf(".env*");
+    const envExampleIndex = currentLines.lastIndexOf("!.env.example");
+    const needsEnv = envIndex === -1;
+    const needsEnvExample = envExampleIndex === -1 || (envIndex !== -1 && envExampleIndex < envIndex) || needsEnv;
+    const missingLines = [
+        ...(currentLines.includes(".humanish/") ? [] : [".humanish/"]),
+        ...(needsEnv ? [".env*"] : []),
+        ...(needsEnvExample ? ["!.env.example"] : []),
+    ];
+    if (missingLines.length === 0) {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "gitignore",
+                reason: "already ignores humanish runtime and env files",
+            },
+        };
+    }
+    const prefix = existing && existing.trim().length > 0 ? trimTrailingNewlines(existing) + "\n\n" : "";
+    const contents = `${prefix}# humanish runtime and local secrets\n${missingLines.join("\n")}\n`;
+    return {
+        write: {
+            absolutePath,
+            relativePath,
+            contents,
+            target: "gitignore",
+        },
+        change: {
+            path: relativePath,
+            action: existing === null ? "create" : "update",
+            target: "gitignore",
+            reason: `add ${missingLines.join(", ")}`,
+        },
+    };
+}
+export async function planPackageJson(projectRoot, cwd) {
+    const relativePath = "package.json";
+    const absolutePath = path.join(cwd, relativePath);
+    const existing = await readTextIfExists(projectRoot, relativePath);
+    if (existing === null) {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "package-json",
+                reason: "package.json not found",
+            },
+            warnings: ["Skipped package.json scripts because package.json was not found."],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "package-json",
+                reason: "package.json is not valid JSON",
+            },
+            warnings: ["package.json is not valid JSON; init did not apply partial changes."],
+            error: {
+                code: "HUMANISH_INVALID_PACKAGE_JSON",
+                message: "package.json is not valid JSON. Fix it before running humanish init.",
+            },
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "package-json",
+                reason: "package.json root is not an object",
+            },
+            warnings: ["package.json root is not an object; init did not apply partial changes."],
+            error: {
+                code: "HUMANISH_INVALID_PACKAGE_JSON",
+                message: "package.json root must be an object. Fix it before running humanish init.",
+            },
+        };
+    }
+    const scripts = isRecord(parsed.scripts) ? { ...parsed.scripts } : {};
+    const missingScripts = {};
+    const conflictingScripts = [];
+    for (const [name, command] of Object.entries(humanishScripts)) {
+        const existingScript = scripts[name];
+        if (existingScript === undefined) {
+            missingScripts[name] = command;
+        }
+        else if (existingScript !== command) {
+            conflictingScripts.push(name);
+        }
+    }
+    if (conflictingScripts.length > 0 && Object.keys(missingScripts).length === 0) {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "package-json",
+                reason: `existing script conflicts: ${conflictingScripts.join(", ")}`,
+            },
+            warnings: [
+                `Skipped package.json script patch because these scripts already exist with different values: ${conflictingScripts.join(", ")}.`,
+            ],
+        };
+    }
+    if (Object.keys(missingScripts).length === 0) {
+        return {
+            change: {
+                path: relativePath,
+                action: "skip",
+                target: "package-json",
+                reason: "humanish scripts already present",
+            },
+            warnings: [],
+        };
+    }
+    parsed.scripts = {
+        ...scripts,
+        ...missingScripts,
+    };
+    const warnings = conflictingScripts.length === 0
+        ? []
+        : [
+            `Preserved existing script values for conflicting scripts: ${conflictingScripts.join(", ")}.`,
+        ];
+    return {
+        write: {
+            absolutePath,
+            relativePath,
+            contents: `${JSON.stringify(parsed, null, 2)}\n`,
+            target: "package-json",
+        },
+        change: {
+            path: relativePath,
+            action: "update",
+            target: "package-json",
+            reason: `add scripts: ${Object.keys(missingScripts).join(", ")}`,
+        },
+        warnings,
+    };
+}
+function trimTrailingNewlines(text) {
+    return text.replace(/\n+$/, "");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lab/init-templates.d.ts

@@ -0,0 +1,28 @@
+import type { LocalAgentId } from "../actors/local-agent/cli.js";
+export interface StarterFile {
+    path: string;
+    contents: string;
+    plane: "source";
+}
+export interface RuntimeDirectory {
+    path: string;
+    plane: "runtime";
+}
+export interface LocalBrowserStarter {
+    appUrl: string;
+    mission: string;
+}
+export declare const DEFAULT_LOCAL_BROWSER_STARTER: LocalBrowserStarter;
+type StarterActor = "openai-computer-use" | "local-agent";
+export declare const starterFiles: StarterFile[];
+export declare const runtimeDirectories: RuntimeDirectory[];
+export declare const humanishScripts: Record<string, string>;
+/**
+ * The starter files, with the live lab written for the brain this machine can use.
+ *
+ * `local-agent` is not a variant of the lab so much as a different participant: on a machine with
+ * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
+ * only E2B. Writing the other one there would hand someone homework instead of a first run.
+ */
+export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId): StarterFile[];
+export {};