humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/doctor.js

@@ -1,12 +1,12 @@
 import path from "node:path";
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy } 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 { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/qualified-versions.js";
+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);
@@ -40,7 +40,7 @@ async function codexAccountReadiness(env) {
 }
 /**
  * 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.
+ * using the study's declared model and reasoning effort as a run would.
  */
 async function hostedCodexReadiness(env, actor) {
     const { checkRestrictedCodexParticipantReadiness } = await import("../actors/codex/restricted-participant.js");
@@ -110,31 +110,44 @@ export async function localCodexParticipantCheck(args) {
         name: "local participant authentication",
         ok: readiness.ready,
         message: readiness.ready
-            ? readyMessage("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.", readiness)
+            ? 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.`,
     };
 }
+/**
+ * The discovery and planning functions doctor's study checks use, loaded on first use as
+ * studySetupChecks 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.listStudyManifests,
+        resolveStudy: discover.resolveStudyManifest,
+        resolveDryRun: plan.resolveStudyDryRun,
+        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
+ * `keys` are the keys a live run requires. `reads` are the provider keys the study is known to read,
+ * required or not; it is undefined when that is unknown: the study 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);
+export async function studySetupChecks(args) {
+    const { resolveStudy, resolveDryRun, routeOf } = await studyLoaders();
+    const resolved = await resolveStudy(args.cwd, args.study);
     if (!resolved.ok)
         return {
             desktop: false,
             keys: [],
-            checks: [{ name: "lab", ok: false, message: resolved.error.message }],
+            checks: [{ name: "study", 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",
+            name: "study route",
             ok: true,
             message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
@@ -159,7 +172,7 @@ export async function labSetupChecks(args) {
     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);
+    const local = isLocalBrowserStudy(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" })));
@@ -298,19 +311,21 @@ 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
-                ? readyMessage("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.", readiness)
+                ? 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")
+        ...(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.",
     };
@@ -326,16 +341,39 @@ function checkScope(analysis) {
     };
 }
 /**
- * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * The ids of the project's labs that need each provider key for a live run, from the same plan
+ * `doctor --study` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A study 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 study 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 });
+    return (await import("./plan.js")).planStudy(config, { cwd });
 }
 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 "This route only creates synthetic evidence. Use first-run in dry-run mode or a supported live study.";
     return undefined;
 }

package/dist/study/field-paths.d.ts

@@ -0,0 +1,12 @@
+import { type Pair, type YAMLMap } from "yaml";
+/** The value at `path`, or for a `[]` segment the values found in each item; undefined if none. */
+export declare function readFieldPath(root: unknown, path: string): unknown;
+/** Delete `path` from a parsed object. Returns whether anything was deleted. */
+export declare function deletePlainFieldPath(root: unknown, path: string): boolean;
+/** The index of `key`'s pair in a YAML mapping, or -1. */
+export declare function pairIndex(map: YAMLMap, key: string): number;
+/**
+ * Delete `path` from a YAML document's root mapping. Returns the deleted pairs, including the
+ * mappings a deletion left empty, so the caller can report their comments.
+ */
+export declare function deleteNodeFieldPath(root: unknown, path: string): Pair[];

package/dist/study/field-paths.js

@@ -0,0 +1,126 @@
+// Dotted field paths such as `execution.timeoutMs` or `actors[0].lanes[].entry`, read and deleted
+// on a parsed object and on a YAML document node. The parsed participant list's key also matches
+// a v2 `roster`, which the parser expands into that list. A mapping a deletion leaves empty is deleted with it.
+import { isMap, isScalar, isSeq } from "yaml";
+function segments(path) {
+    return path.split(".").map((part) => {
+        const match = /^([^[\]]+)(?:\[(\d*)\])?$/.exec(part);
+        if (!match)
+            throw new Error(`Unreadable field path: ${path}`);
+        const [, key, index] = match;
+        if (index === undefined)
+            return { key: key };
+        return { key: key, index: index === "" ? "all" : Number(index) };
+    });
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// `lanes` names the participant list after parsing; a v2 file may spell it `roster`.
+function plainKey(record, key) {
+    return key === "lanes" && !(key in record) && "roster" in record ? "roster" : key;
+}
+function itemsAt(list, index) {
+    if (index === "all")
+        return [...list];
+    const item = list[index];
+    return item === undefined ? [] : [item];
+}
+/** The value at `path`, or for a `[]` segment the values found in each item; undefined if none. */
+export function readFieldPath(root, path) {
+    const read = (value, rest) => {
+        const [segment, ...tail] = rest;
+        if (segment === undefined)
+            return [value];
+        if (!isPlainRecord(value))
+            return [];
+        const child = value[plainKey(value, segment.key)];
+        if (child === undefined)
+            return [];
+        if (segment.index === undefined)
+            return read(child, tail);
+        if (!Array.isArray(child))
+            return [];
+        return itemsAt(child, segment.index).flatMap((item) => read(item, tail));
+    };
+    const parsed = segments(path);
+    const found = read(root, parsed);
+    if (found.length === 0)
+        return undefined;
+    return parsed.some((segment) => segment.index === "all") ? found : found[0];
+}
+/** Delete `path` from a parsed object. Returns whether anything was deleted. */
+export function deletePlainFieldPath(root, path) {
+    const remove = (value, rest) => {
+        const [segment, ...tail] = rest;
+        if (segment === undefined || !isPlainRecord(value))
+            return false;
+        const key = plainKey(value, segment.key);
+        if (!(key in value))
+            return false;
+        const child = value[key];
+        let removed;
+        if (segment.index === undefined) {
+            if (tail.length === 0) {
+                delete value[key];
+                return true;
+            }
+            removed = remove(child, tail);
+        }
+        else {
+            if (!Array.isArray(child))
+                return false;
+            removed = itemsAt(child, segment.index).reduce((any, item) => remove(item, tail) || any, false);
+        }
+        if (removed && isPlainRecord(child) && Object.keys(child).length === 0)
+            delete value[key];
+        return removed;
+    };
+    return remove(root, segments(path));
+}
+function mapKey(map, key) {
+    const has = (name) => map.items.some((pair) => isScalar(pair.key) && pair.key.value === name);
+    return key === "lanes" && !has(key) && has("roster") ? "roster" : key;
+}
+/** The index of `key`'s pair in a YAML mapping, or -1. */
+export function pairIndex(map, key) {
+    return map.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === key);
+}
+/**
+ * Delete `path` from a YAML document's root mapping. Returns the deleted pairs, including the
+ * mappings a deletion left empty, so the caller can report their comments.
+ */
+export function deleteNodeFieldPath(root, path) {
+    const remove = (node, rest) => {
+        const [segment, ...tail] = rest;
+        if (segment === undefined || !isMap(node))
+            return [];
+        const index = pairIndex(node, mapKey(node, segment.key));
+        if (index < 0)
+            return [];
+        const pair = node.items[index];
+        let removed;
+        if (segment.index === undefined) {
+            if (tail.length === 0) {
+                // A mapping holds the comment above its first key; it goes with that key.
+                if (index === 0 && node.commentBefore && isScalar(pair.key)) {
+                    pair.key.commentBefore = [node.commentBefore, pair.key.commentBefore]
+                        .filter(Boolean)
+                        .join("\n");
+                    node.commentBefore = null;
+                }
+                return node.items.splice(index, 1);
+            }
+            removed = remove(pair.value, tail);
+        }
+        else {
+            if (!isSeq(pair.value))
+                return [];
+            removed = itemsAt(pair.value.items, segment.index).flatMap((item) => remove(item, tail));
+        }
+        if (removed.length > 0 && isMap(pair.value) && pair.value.items.length === 0)
+            removed.push(...node.items.splice(index, 1));
+        return removed;
+    };
+    return remove(root, segments(path));
+}

package/dist/study/files.d.ts

@@ -0,0 +1,26 @@
+/** One directory discovery reads study files from. */
+export interface StudyDirectory {
+    readonly relativeDir: string;
+    /** `committed` is the project's own directory; `ignored` ones are gitignored overlays. */
+    readonly origin: "committed" | "ignored";
+    /** `labs` is the directory a `studies/` one replaces. */
+    readonly family: "studies" | "labs";
+}
+/** The six directories, in resolution order. */
+export declare const STUDY_DIRECTORIES: readonly StudyDirectory[];
+/** One path a study named by its stem can have. */
+export interface StudyFileCandidate {
+    readonly relativePath: string;
+    readonly directory: StudyDirectory;
+}
+/** Every path a study with this stem can have, in resolution order. */
+export declare function studyFileCandidates(stem: string): StudyFileCandidate[];
+/** A file name's stem when it is a study file name, else undefined. */
+export declare function studyFileStem(name: string): string | undefined;
+/**
+ * The files that already use `stem` in any of the six directories, other than `except`, which is
+ * the file the writer is about to replace. `exists` reads through the writer's own contained
+ * filesystem checks. A writer skips or refuses when the result is not empty, so no write leaves
+ * two files for one study name.
+ */
+export declare function otherStudyFiles(stem: string, exists: (relativePath: string) => Promise<boolean>, except?: string): Promise<string[]>;

package/dist/study/files.js

@@ -0,0 +1,44 @@
+// Where study files live. Discovery reads the three studies/ directories, and looks in the three
+// labs/ directories they replace only to refuse a file there with its fix. migrate reads all six.
+// Every writer checks a name against all six before it writes, so a new file never shadows another
+// study or takes the name migrate needs to move a labs/ file.
+import path from "node:path";
+/** The six directories, in resolution order. */
+export const STUDY_DIRECTORIES = [
+    { relativeDir: path.join("humanish", "studies"), origin: "committed", family: "studies" },
+    { relativeDir: path.join(".humanish", "studies"), origin: "ignored", family: "studies" },
+    { relativeDir: path.join(".humanish", "local", "studies"), origin: "ignored", family: "studies" },
+    { relativeDir: path.join("humanish", "labs"), origin: "committed", family: "labs" },
+    { relativeDir: path.join(".humanish", "labs"), origin: "ignored", family: "labs" },
+    { relativeDir: path.join(".humanish", "local", "labs"), origin: "ignored", family: "labs" },
+];
+/** A study file's extensions, `.yaml` first. */
+const STUDY_EXTENSIONS = [".yaml", ".yml"];
+/** Every path a study with this stem can have, in resolution order. */
+export function studyFileCandidates(stem) {
+    return STUDY_DIRECTORIES.flatMap((directory) => STUDY_EXTENSIONS.map((extension) => ({
+        relativePath: path.join(directory.relativeDir, `${stem}${extension}`),
+        directory,
+    })));
+}
+/** A file name's stem when it is a study file name, else undefined. */
+export function studyFileStem(name) {
+    const extension = STUDY_EXTENSIONS.find((candidate) => name.endsWith(candidate));
+    return extension === undefined ? undefined : name.slice(0, -extension.length);
+}
+/**
+ * The files that already use `stem` in any of the six directories, other than `except`, which is
+ * the file the writer is about to replace. `exists` reads through the writer's own contained
+ * filesystem checks. A writer skips or refuses when the result is not empty, so no write leaves
+ * two files for one study name.
+ */
+export async function otherStudyFiles(stem, exists, except) {
+    const found = [];
+    for (const candidate of studyFileCandidates(stem)) {
+        if (except !== undefined && path.normalize(candidate.relativePath) === path.normalize(except))
+            continue;
+        if (await exists(candidate.relativePath))
+            found.push(candidate.relativePath);
+    }
+    return found;
+}

package/dist/{lab → study}/init-templates.d.ts

@@ -18,9 +18,9 @@ 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.
+ * The starter files, with the live study 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
+ * `local-agent` is not a variant of the study 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.
  */