humanish 0.106.1 → 0.108.0

package/dist/lab/doctor.js

@@ -1,25 +1,107 @@
+import path from "node:path";
 import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
+import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
+import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.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. */
+import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
+/** A ready row's message, with the schema values the launch recorded. */
+function readyMessage(message, readiness) {
+    const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
+    return additions === undefined ? message : `${message} ${additions}`;
+}
+/** npm's global prefix (`npm prefix -g`), or undefined when npm does not answer. */
+async function npmGlobalPrefix(env) {
+    const { execFile } = await import("node:child_process");
+    return new Promise((resolve) => {
+        execFile("npm", ["prefix", "-g"], { env, timeout: 5000 }, (error, stdout) => {
+            const prefix = String(stdout).trim();
+            resolve(error === null && path.isAbsolute(prefix) ? prefix : undefined);
+        });
+    });
+}
+/** Where the `codex` on `PATH` was installed; npm's prefix is read only when not project-local. */
+async function codexInstallation(env) {
+    const { foundCodexExecutable } = await import("../actors/codex/restricted-executable.js");
+    const found = await foundCodexExecutable(env).catch(() => undefined);
+    if (found === undefined)
+        return undefined;
+    const local = classifyCodexInstallation(found, undefined);
+    return local.kind === "project"
+        ? local
+        : classifyCodexInstallation(found, await npmGlobalPrefix(env));
+}
+/** The account check doctor and the TUI share: the isolated launch, with recovery details. */
 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 checked = await (await import("../analysis/restricted-codex.js")).checkRestrictedCodexAnalysisReadiness({ timeoutMs: 5000 }, { env });
+    return withCodexRecoveryDetails(env, checked);
+}
+/**
+ * The hosted participant check: the operator-auth launch to an ephemeral thread, with no turn,
+ * using the lab's declared model and reasoning effort as a run would.
+ */
+async function hostedCodexReadiness(env, actor) {
+    const { checkRestrictedCodexParticipantReadiness } = await import("../actors/codex/restricted-participant.js");
+    const checked = await checkRestrictedCodexParticipantReadiness({
+        session: { env },
+        ...(actor.model === undefined ? {} : { model: actor.model }),
+        ...(actor.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
+    });
+    return checked.ready
+        ? checked
+        : { ...checked, ...(await withCodexRecoveryDetails(env, checked)) };
+}
+/**
+ * Adds what the recovery line names to a failed check. An unadmitted CLI gets its release, an
+ * unavailable one the file humanish turned down, and both where the binary came from.
+ */
+async function withCodexRecoveryDetails(env, checked) {
+    if (checked.errorCode !== "codex_unavailable" &&
+        checked.errorCode !== "codex_unsupported_version" &&
+        checked.errorCode !== "codex_incompatible_release")
+        return checked;
+    const installation = await codexInstallation(env);
+    const readiness = installation === undefined ? checked : { ...checked, installation };
+    if (readiness.errorCode === "codex_unavailable") {
+        const { refusedCodexExecutable } = await import("../actors/codex/restricted-executable.js");
+        const refused = await refusedCodexExecutable(env).catch(() => undefined);
+        return refused === undefined ? readiness : { ...readiness, refusedExecutable: refused };
+    }
     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. */
+/**
+ * What to do about a Codex readiness failure, one line per code: an unadmitted CLI gets its exact
+ * install command, a missing login `codex login`, and an unavailable CLI the file humanish turned
+ * down and why. Other codes get `fallback`.
+ */
 function codexRecovery(readiness, fallback) {
-    return readiness.errorCode === "codex_unsupported_version"
-        ? codexVersionRecovery(readiness.detectedCliVersion)
-        : fallback;
+    switch (readiness.errorCode) {
+        case "codex_unsupported_version":
+            return codexVersionRecovery(readiness.detectedCliVersion, readiness.installation);
+        case "codex_incompatible_release":
+            return `${protocolIncompatibilityMessage(readiness.detectedCliVersion, readiness.protocolIncompatibilities ?? [])} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        case "codex_login_required":
+            return "Codex is installed but not signed in. Run `codex login` and sign in with a ChatGPT account.";
+        case "codex_unsupported_auth":
+            return "Codex is signed in without a ChatGPT account, for example with an API key. Run `codex logout`, then `codex login` with a ChatGPT account.";
+        case "codex_unavailable": {
+            const refused = readiness.refusedExecutable;
+            const found = refused === undefined
+                ? "humanish could not start the Codex CLI."
+                : refused.path === undefined
+                    ? `Codex is unavailable: ${refused.reason}.`
+                    : `humanish found \`${refused.path}\` and cannot run it: ${refused.reason}.`;
+            return `${found} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        }
+        default:
+            return fallback;
+    }
 }
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export async function localCodexParticipantCheck(args) {
@@ -28,15 +110,33 @@ export async function localCodexParticipantCheck(args) {
         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."
+            ? readyMessage("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.", readiness)
             : `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. */
+/**
+ * The discovery and planning functions doctor's study checks use, loaded on first use as
+ * labSetupChecks always loaded them, so they stay out of this module's static imports.
+ */
+async function studyLoaders() {
+    const discover = await import("./discover.js");
+    const plan = await import("./plan.js");
+    return {
+        listStudies: discover.listLabManifests,
+        resolveStudy: discover.resolveLabManifest,
+        resolveDryRun: plan.resolveLabDryRun,
+        routeOf: plan.routeOf,
+    };
+}
+/**
+ * Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network.
+ * `keys` are the keys a live run requires. `reads` are the provider keys the lab is known to read,
+ * required or not; it is undefined when that is unknown: the lab does not plan, or a declared
+ * scorer's host code may read any key.
+ */
 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);
+    const { resolveStudy, resolveDryRun, routeOf } = await studyLoaders();
+    const resolved = await resolveStudy(args.cwd, args.lab);
     if (!resolved.ok)
         return {
             desktop: false,
@@ -44,7 +144,7 @@ export async function labSetupChecks(args) {
             checks: [{ name: "lab", ok: false, message: resolved.error.message }],
         };
     const config = resolved.config, route = routeOf(config);
-    const dryRun = resolveLabDryRun(config, undefined, true) === true;
+    const dryRun = resolveDryRun(config, undefined, true) === true;
     const checks = [
         {
             name: "lab route",
@@ -53,7 +153,7 @@ export async function labSetupChecks(args) {
         },
     ];
     if (dryRun)
-        return { desktop: false, keys: [], checks };
+        return { desktop: false, keys: [], reads: new Set(), checks };
     const unsupported = unsupportedCliRoute(config, route);
     if (unsupported)
         return {
@@ -61,7 +161,17 @@ export async function labSetupChecks(args) {
             keys: [],
             checks: [...checks, { name: "live route", ok: false, message: unsupported }],
         };
-    const { desktop, keys } = labKeyRequirements(config, route, false, args.keyPresent);
+    const planned = await planCliRun(config, args.cwd);
+    if (!planned.ok)
+        return {
+            desktop: false,
+            keys: [],
+            checks: [...checks, { name: "live route", ok: false, message: planned.refusal.message }],
+        };
+    const requirements = planned.planned.plan.requirements;
+    const keys = requiredKeys(requirements, args.keyPresent);
+    // This flag controls the hosted desktop SDK check as well as its API key.
+    const desktop = keys.includes("E2B_API_KEY");
     const local = isLocalBrowserLab(config);
     // One account check, shared by the local participant row and the Codex analysis row.
     let accountReadiness;
@@ -73,12 +183,15 @@ export async function labSetupChecks(args) {
     checks.push(...(await participantChecks(config, route, keys, local, args, checkAccount)));
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
-    checks.push(...subjectEnvChecks(config, args));
+    checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), 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 };
+    const reads = config.review?.scorer === undefined
+        ? new Set([...keyNamesOf(planned.planned.plan), ...keys])
+        : undefined;
+    return { desktop, keys, ...(reads === undefined ? {} : { reads }), checks };
 }
 /** A local browser study's runtime and, with an external catch, its captured inbox. */
 async function localBrowserChecks(config, args) {
@@ -137,6 +250,10 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
+    // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
+    // that the operator's config, release and model admit a launch.
+    if (choice === "codex" && agent?.authStatus === "authenticated")
+        return [await hostedCodexParticipantCheck(args, config.actors[0])];
     return [
         {
             name: "local participant authentication",
@@ -149,6 +266,24 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         },
     ];
 }
+/** The hosted Codex participant row: what the operator handshake admitted, or how to fix it. */
+async function hostedCodexParticipantCheck(args, actor) {
+    const declared = {
+        ...(actor?.model === undefined ? {} : { model: actor.model }),
+        ...(actor?.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
+    };
+    const readiness = await (args.codexParticipantReadiness ?? hostedCodexReadiness)(args.env, declared).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
+    const account = readiness.authentication === "api-key"
+        ? "an API key, which bills its usage to that key"
+        : "a ChatGPT account";
+    return {
+        name: "local participant authentication",
+        ok: readiness.ready,
+        message: readiness.ready
+            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.`, readiness)
+            : `Hosted Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Check `codex login status` and the operator's Codex configuration, then rerun doctor.")} No API fallback is used.`,
+    };
+}
 /** The local Chrome/Chromium the scripted-browser route drives. */
 async function scriptedBrowserCheck() {
     const { resolveBrowserCommand } = await import("../actors/scripted-browser/browser-command.js");
@@ -158,9 +293,9 @@ async function scriptedBrowserCheck() {
         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) => ({
+/** One row per subject env name the plan requires: present or missing, never the value. */
+function subjectEnvChecks(names, args) {
+    return names.map((name) => ({
         name: `subject env ${name}`,
         ok: !!args.env[name]?.trim() || args.keyPresent(name),
         message: args.env[name]?.trim() || args.keyPresent(name)
@@ -168,7 +303,7 @@ function subjectEnvChecks(config, args) {
             : "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. */
+/** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
@@ -176,20 +311,22 @@ async function analysisCheck(analysis, args, checkAccount) {
             ? "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.");
+                : codexRecovery(readiness, "Install the Codex 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."
+                ? readyMessage("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.", readiness)
                 : `Codex account analysis is unavailable (${readiness.errorCode ?? "codex_unavailable"}). ${recovery} No API fallback is used; participant readiness is independent.`,
         };
     }
+    const keyed = args.keyPresent("OPENAI_API_KEY");
     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.`
+        ...(keyed ? {} : { status: "note" }),
+        message: keyed
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its estimate is over $${analysis.maxCostUsd}; this is not a 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.",
     };
 }
@@ -203,26 +340,35 @@ function checkScope(analysis) {
             : "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 };
+/**
+ * The ids of the project's labs that need each provider key for a live run, from the same plan
+ * `doctor --lab` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A lab that runs dry, that the plain CLI cannot run, or that does not plan needs
+ * none.
+ */
+export async function studiesByRequiredKey(cwd, keyPresent) {
+    const { listStudies, resolveStudy, resolveDryRun, routeOf } = await studyLoaders();
+    const users = new Map();
+    for (const entry of (await listStudies(cwd)).studies) {
+        const resolved = await resolveStudy(cwd, entry.path);
+        if (!resolved.ok || resolveDryRun(resolved.config, undefined, true) === true)
+            continue;
+        if (unsupportedCliRoute(resolved.config, routeOf(resolved.config)))
+            continue;
+        const planned = await planCliRun(resolved.config, cwd);
+        if (!planned.ok)
+            continue;
+        for (const key of requiredKeys(planned.planned.plan.requirements, keyPresent))
+            users.set(key, (users.get(key) ?? new Set()).add(entry.id));
+    }
+    return new Map([...users].map(([key, ids]) => [key, [...ids]]));
+}
+/**
+ * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * TUI read a live run's keys and subject env from this plan's requirements.
+ */
+export async function planCliRun(config, cwd) {
+    return (await import("./plan.js")).planLab(config, { cwd });
 }
 function unsupportedCliRoute(config, route) {
     if (config.subject.source === "local-app")

package/dist/lab/init-plan.js

@@ -3,6 +3,7 @@
 // here; runInit applies the plan.
 import path from "node:path";
 import { humanishScripts } from "./init-templates.js";
+import { isRecord } from "../run/type-guards.js";
 import { readTextIfExists } from "./init-paths.js";
 export async function planGitignore(projectRoot, cwd) {
     const relativePath = ".gitignore";
@@ -158,6 +159,3 @@ export async function planPackageJson(projectRoot, cwd) {
 function trimTrailingNewlines(text) {
     return text.replace(/\n+$/, "");
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}