humanish 0.115.0 → 0.117.0

package/dist/guest/desktop-keys.js

@@ -3,18 +3,35 @@ import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.
 // hand these strings to xdotool, which has a command language, so only names from these tables
 // ever reach it. The guest runtime ships this module, so it lives in src/guest/, which CI's
 // guest-desktop job and scripts/guest-desktop-proof.mjs key on.
+//
+// The tables take the names in OpenAI's computer-use key map, the names @e2b/desktop's press()
+// mapped (the hosted desktop sent keys through it before), and every printable ASCII
+// punctuation character. xdotool finds the key and the Shift level for a keysym itself, so `?`
+// arrives as `question` with Shift held on an American English keymap.
 /** The modifiers a pointer action may hold, keyed by the upper-cased provider name. */
 const modifierNames = Object.freeze({
     CTRL: "ctrl",
     CONTROL: "ctrl",
     ALT: "alt",
+    OPTION: "alt",
     SHIFT: "shift",
     META: "super",
     SUPER: "super",
     CMD: "super",
+    COMMAND: "super",
+    WIN: "super",
+    WINDOWS: "super",
 });
 const keyNames = Object.freeze({
     ...modifierNames,
+    CONTROL_LEFT: "Control_L",
+    CONTROL_RIGHT: "Control_R",
+    ALT_LEFT: "Alt_L",
+    ALT_RIGHT: "Alt_R",
+    SHIFT_LEFT: "Shift_L",
+    SHIFT_RIGHT: "Shift_R",
+    SUPER_LEFT: "Super_L",
+    SUPER_RIGHT: "Super_R",
     ENTER: "Return",
     RETURN: "Return",
     TAB: "Tab",
@@ -24,11 +41,14 @@ const keyNames = Object.freeze({
     " ": "space",
     BACKSPACE: "BackSpace",
     DELETE: "Delete",
+    DEL: "Delete",
     INSERT: "Insert",
     HOME: "Home",
     END: "End",
     PAGEUP: "Prior",
     PAGEDOWN: "Next",
+    PAGE_UP: "Prior",
+    PAGE_DOWN: "Next",
     ARROWUP: "Up",
     ARROWDOWN: "Down",
     ARROWLEFT: "Left",
@@ -37,18 +57,45 @@ const keyNames = Object.freeze({
     DOWN: "Down",
     LEFT: "Left",
     RIGHT: "Right",
+    CAPS_LOCK: "Caps_Lock",
+    NUM_LOCK: "Num_Lock",
+    SCROLL_LOCK: "Scroll_Lock",
+    PAUSE: "Pause",
+    BREAK: "Pause",
+    PRINT: "Print",
+    MENU: "Menu",
+    "!": "exclam",
+    '"': "quotedbl",
+    "#": "numbersign",
+    $: "dollar",
+    "%": "percent",
+    "&": "ampersand",
+    "'": "apostrophe",
+    "(": "parenleft",
+    ")": "parenright",
+    "*": "asterisk",
     "+": "plus",
-    "-": "minus",
-    "=": "equal",
     ",": "comma",
+    "-": "minus",
     ".": "period",
     "/": "slash",
-    "\\": "backslash",
+    ":": "colon",
     ";": "semicolon",
-    "'": "apostrophe",
+    "<": "less",
+    "=": "equal",
+    ">": "greater",
+    "?": "question",
+    "@": "at",
     "[": "bracketleft",
+    "\\": "backslash",
     "]": "bracketright",
+    "^": "asciicircum",
+    _: "underscore",
     "`": "grave",
+    "{": "braceleft",
+    "|": "bar",
+    "}": "braceright",
+    "~": "asciitilde",
 });
 function lookup(table, key) {
     const upper = key.toUpperCase();
@@ -59,9 +106,16 @@ function chord(names) {
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     return names.join("+");
 }
+/**
+ * A name that is itself a chord (`Control+a`, `ctrl++`) split at each plus sign that joins two
+ * names. A lone `+` and a trailing `+` after a joining one are the plus key.
+ */
+function chordParts(key) {
+    return key.length > 1 ? key.split(/\+(?!$)/) : [key];
+}
 /** A keypress chord in xdotool syntax. Unknown or repeated keys are refused before dispatch. */
 export function xdotoolChord(keys) {
-    return chord(keys.map((key) => {
+    return chord(keys.flatMap(chordParts).map((key) => {
         if (/^[a-z0-9]$/i.test(key))
             return key.toLowerCase();
         if (/^F(?:[1-9]|1[0-2])$/i.test(key))

package/dist/keys/key-resolution.d.ts

@@ -1,3 +1,12 @@
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export declare const KEY_VENDORS: string[];
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export declare const LISTED_KEYS: {
+    name: string;
+    use: string;
+}[];
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export declare const DOCTOR_KEYS: string[];
 export interface ResolvedKeyFill {
     name: string;
     /** Human-readable source label (a path or command name), never a value. */

package/dist/keys/key-resolution.js

@@ -24,33 +24,56 @@ import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
 import { humanishConfigFile } from "../cli/user-config.js";
 import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
-/** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
- *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
- *  must never enter process env off a file the operator did not explicitly pass (an explicit
- *  --dotenv remains the operator's own full-file load). */
-const KNOWN_PROVIDER_KEYS = [
-    "OPENAI_API_KEY",
-    "ANTHROPIC_API_KEY",
-    "E2B_API_KEY",
-    "GH_TOKEN",
-    "GITHUB_TOKEN",
-    "CODEX_API_KEY",
-    "AGENTMAIL_API_KEY",
+/**
+ * The provider keys, in the order `humanish keys set` names their vendors. Implicit discovery fills
+ * only these names and the user store holds only these. Everything else in an overlay or store file
+ * is ignored and named: a repo-planted NODE_OPTIONS/LD_PRELOAD must never enter process env off a
+ * file the operator did not explicitly pass (an explicit --dotenv remains the operator's own
+ * full-file load). ANTHROPIC_API_KEY is not listed, and doctor does not report it: a Claude Code
+ * participant runs on its own login and never receives it. CODEX_API_KEY is an alternative spelling
+ * of the OpenAI key for terminal studies. Doctor reports AGENTMAIL_API_KEY only under `--study`, for
+ * a study whose email connection names it, since a connection may name another variable.
+ */
+const PROVIDER_KEYS = [
+    {
+        name: "OPENAI_API_KEY",
+        vendor: "openai",
+        listed: { order: 2, use: "participant model and analysis" },
+        doctor: true,
+    },
+    {
+        name: "E2B_API_KEY",
+        vendor: "e2b",
+        login: "e2b auth login",
+        listed: { order: 1, use: "hosted desktops" },
+        doctor: true,
+    },
+    { name: "ANTHROPIC_API_KEY", vendor: "anthropic" },
+    {
+        name: "GH_TOKEN",
+        vendor: "github",
+        login: "gh auth login",
+        listed: { order: 3, use: "private repository subjects" },
+        doctor: true,
+    },
+    { name: "GITHUB_TOKEN", spellingOf: "GH_TOKEN" },
+    { name: "CODEX_API_KEY", doctor: true },
+    { name: "AGENTMAIL_API_KEY", vendor: "agentmail", listed: { order: 4, use: "email in studies" } },
 ];
-const PROVIDER_KEY_SET = new Set(KNOWN_PROVIDER_KEYS);
+const PROVIDER_KEY_SET = new Set(PROVIDER_KEYS.map((key) => key.name));
+const providerKey = (name) => PROVIDER_KEYS.find((key) => key.name === name);
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export const KEY_VENDORS = PROVIDER_KEYS.flatMap((key) => key.vendor === undefined ? [] : [key.vendor]);
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export const LISTED_KEYS = PROVIDER_KEYS.flatMap(({ name, listed }) => listed === undefined ? [] : [{ name, ...listed }])
+    .sort((a, b) => a.order - b.order)
+    .map(({ name, use }) => ({ name, use }));
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export const DOCTOR_KEYS = PROVIDER_KEYS.flatMap(({ name, doctor }) => (doctor ? [name] : []));
 /** An env for a vendor CLI that discovery runs: the caller's, without any provider key name. */
 function withoutProviderKeys(env) {
     return Object.fromEntries(Object.entries(env).filter(([name]) => !PROVIDER_KEY_SET.has(name)));
 }
-/** `humanish keys set <vendor>` aliases; a raw ENV_NAME is also accepted. A Map, so a name such as
- * `constructor` is no alias. */
-const KEY_VENDOR_ALIASES = new Map([
-    ["openai", "OPENAI_API_KEY"],
-    ["e2b", "E2B_API_KEY"],
-    ["anthropic", "ANTHROPIC_API_KEY"],
-    ["github", "GH_TOKEN"],
-    ["agentmail", "AGENTMAIL_API_KEY"],
-]);
 const PROJECT_OVERLAY_RELATIVE = path.join(".humanish", "local", "provider.env");
 export function userKeyStorePath(env, deps = {}) {
     return humanishConfigFile(env, "keys.env", deps.homeDir);
@@ -230,21 +253,10 @@ function storeLabel(env, deps) {
 /** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
  *  *_KEYS_MISSING errors so the failure names the fix. */
 export function missingKeyHint(name) {
-    switch (name) {
-        case "E2B_API_KEY":
-            return `run \`e2b auth login\`, or \`${cli("keys set e2b")}\``;
-        case "GH_TOKEN":
-        case "GITHUB_TOKEN":
-            return `run \`gh auth login\`, or \`${cli("keys set github")}\``;
-        case "OPENAI_API_KEY":
-            return `run \`${cli("keys set openai")}\``;
-        case "ANTHROPIC_API_KEY":
-            return `run \`${cli("keys set anthropic")}\``;
-        case "AGENTMAIL_API_KEY":
-            return `run \`${cli("keys set agentmail")}\``;
-        default:
-            return `run \`${cli(`keys set ${name}`)}\``;
-    }
+    const named = providerKey(name);
+    const key = named?.spellingOf === undefined ? named : providerKey(named.spellingOf);
+    const set = `\`${cli(`keys set ${key?.vendor ?? name}`)}\``;
+    return key?.login === undefined ? `run ${set}` : `run \`${key.login}\`, or ${set}`;
 }
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each
  *  missing key. Pure text; never values. */
@@ -276,19 +288,18 @@ export async function probeKeySources(names, args) {
         ...(args.deps === undefined ? {} : { deps: args.deps }),
     });
     const bySource = new Map(fills.map((fill) => [fill.name, fill.source]));
+    const setInEnv = (name) => args.env[name] !== undefined && args.env[name]?.trim() !== "";
     return names.map((name) => {
-        const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "" && !placeholder(name);
-        // GH_TOKEN and GITHUB_TOKEN are one credential with two spellings; a doctor row that says
-        // "missing" while GITHUB_TOKEN sits in the env would be wrong.
-        const aliasInEnv = name === "GH_TOKEN" &&
-            args.env.GITHUB_TOKEN !== undefined &&
-            args.env.GITHUB_TOKEN.trim() !== "";
+        const inEnv = setInEnv(name) && !placeholder(name);
+        // A second spelling of the key in the env, such as GITHUB_TOKEN for GH_TOKEN, is the same
+        // credential; a doctor row that says "missing" while it sits in the env would be wrong.
+        const spelling = PROVIDER_KEYS.find((key) => key.spellingOf === name && setInEnv(key.name))?.name;
         const source = inEnv
             ? args.dotenv?.names.includes(name)
                 ? `--dotenv ${args.dotenv.path}`
                 : "process env"
-            : aliasInEnv
-                ? "process env (GITHUB_TOKEN)"
+            : spelling !== undefined
+                ? `process env (${spelling})`
                 : (bySource.get(name) ?? null);
         return {
             name,
@@ -301,9 +312,10 @@ export async function probeKeySources(names, args) {
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Resolve a `humanish keys set` target: a vendor alias or a raw env name. Null = invalid. */
 export function resolveKeyName(vendorOrName) {
-    const alias = KEY_VENDOR_ALIASES.get(vendorOrName.toLowerCase());
-    if (alias !== undefined)
-        return alias;
+    const vendor = vendorOrName.toLowerCase();
+    const key = PROVIDER_KEYS.find((candidate) => candidate.vendor === vendor);
+    if (key !== undefined)
+        return key.name;
     return ENV_NAME.test(vendorOrName) ? vendorOrName : null;
 }
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names

package/dist/keys/key-status.d.ts

@@ -10,6 +10,8 @@ export declare function keyStatus(args: {
 }): Promise<KeyStatusRow[]>;
 /** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
 export declare function otherStoredKeys(env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): string[];
+/** The line `humanish keys` prints for one key: what it is for, and its source or how to add it. */
+export declare function keyStatusLine(row: KeyStatusRow): string;
 export declare function formatKeyStatus(rows: readonly KeyStatusRow[], otherStored?: readonly string[]): string;
 interface MissingKeysOutcome {
     stored: string[];

package/dist/keys/key-status.js

@@ -1,33 +1,26 @@
 // `humanish keys`: which provider keys are set and where each comes from, through the same chain a
 // live command resolves. Never a value.
 import { cli } from "../cli/invocation.js";
-import { listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
-/**
- * The keys a person sets for humanish, in the order the status lists them and `keys set` asks for
- * them. ANTHROPIC_API_KEY is left out: a Claude Code participant runs on its own login and never
- * receives it. CODEX_API_KEY is an alternative spelling of the OpenAI key for terminal studies.
- */
-const STATUS_KEYS = [
-    { name: "E2B_API_KEY", use: "hosted desktops" },
-    { name: "OPENAI_API_KEY", use: "participant model and analysis" },
-    { name: "GH_TOKEN", use: "private repository subjects" },
-    { name: "AGENTMAIL_API_KEY", use: "email in studies" },
-];
+import { LISTED_KEYS, listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
 export async function keyStatus(args) {
-    const probes = await probeKeySources(STATUS_KEYS.map((key) => key.name), {
+    const probes = await probeKeySources(LISTED_KEYS.map((key) => key.name), {
         cwd: args.cwd,
         env: args.env,
         ...(args.deps === undefined ? {} : { deps: args.deps }),
     });
-    return probes.map((probe, index) => ({ ...probe, use: STATUS_KEYS[index].use }));
+    return probes.map((probe, index) => ({ ...probe, use: LISTED_KEYS[index].use }));
 }
 /** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
 export function otherStoredKeys(env, deps = {}) {
-    const listed = new Set(STATUS_KEYS.map((key) => key.name));
+    const listed = new Set(LISTED_KEYS.map((key) => key.name));
     return listUserKeys(env, deps).filter((name) => !listed.has(name));
 }
+/** The line `humanish keys` prints for one key: what it is for, and its source or how to add it. */
+export function keyStatusLine(row) {
+    return `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`;
+}
 export function formatKeyStatus(rows, otherStored = []) {
-    const lines = rows.map((row) => `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`);
+    const lines = rows.map(keyStatusLine);
     if (otherStored.length > 0)
         lines.push(`Also in the user store: ${otherStored.join(", ")}. humanish does not use ${otherStored.length === 1 ? "it" : "them"} today.`);
     const missing = rows.some((row) => row.source === null);

package/dist/observer/pinned-files.js

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
-import { readOpenedAtMost } from "../run/evidence-files.js";
+import { readOpenedAtMost } from "../run/contained-output.js";
 import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a

package/dist/observer/render.js

@@ -11,7 +11,7 @@ import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { physicalCwdOf, runIdOf, bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { writeContainedOutputFile } from "../run/contained-output.js";
-import { loadRunBundlePrepared, readRunJsonIfExists } from "../run/locate.js";
+import { loadRunBundlePrepared, readRunJsonIfExists, runJsonValue } from "../run/locate.js";
 import { readRunNotes } from "../run/note-files.js";
 import { RUN_STATUS_FILE } from "../run/status.js";
 import { verifyRunPrepared } from "../verify/verify.js";
@@ -106,8 +106,9 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
     };
     // A run.json without an outcome is in progress, interrupted, or older than the field: its
     // status.json says which, and holds an older run's ok.
+    // A status.json it refuses says nothing, as a missing one does: the bundle's own facts show.
     const statusRecord = loaded.bundle.outcome === undefined
-        ? await readRunJsonIfExists(preparedRunPaths, RUN_STATUS_FILE)
+        ? runJsonValue(await readRunJsonIfExists(preparedRunPaths, RUN_STATUS_FILE))
         : undefined;
     const observerData = buildObserverData(loaded.bundle, undefined, statusRecord);
     observerData.publicSafety.share = {