humanish 0.94.0 → 0.96.0

package/dist/program.d.ts

@@ -1,6 +1,8 @@
 import { type AutomaticAnalysisHooks } from "./automatic-analysis-completion.js";
 import { Command } from "commander";
 import { discoverProviderKeys } from "./key-resolution.js";
+import { checkCommsConnection } from "./comms-setup.js";
+import { promptSecret } from "./secret-prompt.js";
 import { type TelemetryProperties } from "./telemetry.js";
 import type { CuaActorLabResult } from "./cua-actor-lab.js";
 import type { ObserverResult, ObserverServer } from "./observer.js";
@@ -39,6 +41,8 @@ export declare function createProgram(io?: Partial<CliIo> & {
  * TTY, an old Node, or a missing bundle appear.
  */
 export interface TuiRuntime {
+    checkComms: typeof checkCommsConnection;
+    promptSecret: typeof promptSecret;
     stdin: NodeJS.ReadStream;
     stdout: NodeJS.WriteStream;
     nodeVersion: string;

package/dist/program.js

@@ -10,6 +10,11 @@ import { Command, Option } from "commander";
 import { startCodexAppServerUi } from "./codex-app-server-ui.js";
 import { loadEnvFile } from "./env-file.js";
 import { discoverProviderKeys, listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath } from "./key-resolution.js";
+import { COMMS_PROVIDERS, readCommsSetup, saveCommsConnection } from "./comms-connections.js";
+import { checkCommsConnection, configureCommsLab } from "./comms-setup.js";
+import { inspectCommsRecovery, recoverCommsReceiving } from "./comms-receiving.js";
+import { resolveReceivingConnection } from "./comms-receiving-runtime.js";
+import { promptSecret } from "./secret-prompt.js";
 import { redactText } from "./redaction.js";
 import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback } from "./feedback.js";
 import { runInit } from "./init.js";
@@ -461,6 +466,8 @@ function registerDoctorCommand(parent, io) {
     });
 }
 const defaultTuiRuntime = {
+    checkComms: checkCommsConnection,
+    promptSecret,
     stdin: process.stdin,
     stdout: process.stdout,
     env: process.env,
@@ -560,10 +567,14 @@ function registerTuiCommand(parent, io) {
         .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
         .summary("Human terminal for labs and runs; refuses detected agent sessions and non-TTY input/output. Agents: humanish lab list --json, humanish lab inspect <lab> --json, humanish runs --json.")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this terminal session and its runs without printing values.")
         .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
         const { stdin, stdout } = tuiRuntime;
+        // Production uses process.env, including SDKs used by existing cleanup actions. Tests inject
+        // an isolated host context. Values stay behind the capability closures, never in view data.
+        const sessionEnv = tuiRuntime.env;
         // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands
         // it runs, so the TTY check below passes and the surface used to open: a study watched an
         // agent navigate the labs list and start a run it did not mean to start
@@ -623,43 +634,110 @@ function registerTuiCommand(parent, io) {
             });
             return;
         }
+        const discoveredKeys = new Set();
+        if (!await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io, env: sessionEnv,
+            onDiscovered: names => names.forEach(name => discoveredKeys.add(name)) }))
+            return;
+        // Probe stored credentials afresh. Discovery fills must not become permanent env overrides
+        // when a person replaces a stored key during this terminal session.
+        const connectionEnv = () => {
+            const env = { ...sessionEnv };
+            for (const name of discoveredKeys)
+                delete env[name];
+            return env;
+        };
         const observerSession = createTuiObserverSession(resolve(options.cwd));
-        let exitCode;
+        let exitCode = 0;
+        let connectionNotice;
+        let connectionCheck;
         try {
-            exitCode = await loaded.startTui({
-                cwd: resolve(options.cwd),
-                version: { cli: CLI_VERSION },
-                capabilities: {
-                    // One cache for the life of the surface: it refreshes on a cadence, and re-walking every
-                    // run tree each tick is the cost this index exists to avoid.
-                    readRunIndex: (target, readOptions) => readRunIndex(target, { ...readOptions, cache: runIndexCache }),
-                    listLabs: listLabManifests,
-                    startRun: launchRun,
-                    readLaunchLog: readLaunchLogTail,
-                    readRunDetail,
-                    readLabSummary,
-                    readProjectState,
-                    openObserver: (target, observerPath) => observerSession.open(target, observerPath),
-                    reclaimRun: (target, runId) => reclaimRunSandboxes(target, runId),
-                    stopRun,
-                    initProject: async (target) => {
-                        const result = await runInit({ cwd: target, yes: true });
-                        return result.ok
-                            ? {
-                                schema: TUI_ACTION_SCHEMA,
-                                ok: true,
-                                message: `set up humanish here — ${result.changes.filter((change) => change.action !== "skip").length} files written`
+            for (;;) {
+                const outcome = await loaded.startTui({
+                    ...(connectionNotice === undefined ? {} : { initialScreen: "connections", connectionNotice }),
+                    cwd: resolve(options.cwd),
+                    version: { cli: CLI_VERSION },
+                    capabilities: {
+                        comms: {
+                            read: async () => ({ ...await readCommsSetup(resolve(options.cwd), connectionEnv()), ...(connectionCheck ? { authentication: connectionCheck } : {}) }),
+                            save: () => saveCommsConnection(resolve(options.cwd)),
+                            check: async () => { connectionCheck = await tuiRuntime.checkComms({ cwd: resolve(options.cwd), env: connectionEnv(), online: true }); return connectionCheck; },
+                            labs: async () => (await listLabManifests(resolve(options.cwd))).labs.map(lab => ({ title: lab.title ?? lab.id, path: lab.path })),
+                            configure: (lab, apply, planToken) => configureCommsLab({ cwd: resolve(options.cwd), lab, connection: "agentmail", apply, ...(planToken ? { planToken } : {}) }),
+                            recovery: () => inspectCommsRecovery({ cwd: resolve(options.cwd) }),
+                            recover: async (runId, connectionName) => {
+                                try {
+                                    const { connection, adapter } = await resolveReceivingConnection(resolve(options.cwd), connectionName, connectionEnv());
+                                    return await recoverCommsReceiving({ cwd: resolve(options.cwd), runId, connectionName, apiKeyEnv: connection.apiKeyEnv, adapter });
+                                }
+                                catch {
+                                    return { ok: false, message: "Could not recover email resources. Check the connection and retry." };
+                                }
                             }
-                            : {
-                                schema: TUI_ACTION_SCHEMA,
-                                ok: false,
-                                message: result.error?.message ?? "humanish init could not set this directory up"
-                            };
-                    }
-                },
-                stdin,
-                stdout
-            });
+                        },
+                        // One cache for the life of the surface: it refreshes on a cadence, and re-walking every
+                        // run tree each tick is the cost this index exists to avoid.
+                        readRunIndex: (target, readOptions) => readRunIndex(target, { ...readOptions, cache: runIndexCache }),
+                        listLabs: listLabManifests,
+                        startRun: launchOptions => launchRun({ ...launchOptions, env: sessionEnv }),
+                        readLaunchLog: readLaunchLogTail,
+                        readRunDetail,
+                        readLabSummary: (target, lab, readOptions) => readLabSummary(target, lab, { ...readOptions, env: sessionEnv }),
+                        readProjectState,
+                        openObserver: (target, observerPath) => observerSession.open(target, observerPath),
+                        reclaimRun: (target, runId) => reclaimRunSandboxes(target, runId),
+                        stopRun,
+                        initProject: async (target) => {
+                            const result = await runInit({ cwd: target, yes: true });
+                            return result.ok
+                                ? {
+                                    schema: TUI_ACTION_SCHEMA,
+                                    ok: true,
+                                    message: `set up humanish here — ${result.changes.filter((change) => change.action !== "skip").length} files written`
+                                }
+                                : {
+                                    schema: TUI_ACTION_SCHEMA,
+                                    ok: false,
+                                    message: result.error?.message ?? "humanish init could not set this directory up"
+                                };
+                        }
+                    },
+                    stdin,
+                    stdout
+                });
+                if (typeof outcome === "number") {
+                    exitCode = outcome;
+                    break;
+                }
+                if (outcome.action !== "agentmail-key") {
+                    exitCode = 1;
+                    break;
+                }
+                // startTui has unmounted: only the host reads the credential, then remounts the view.
+                const value = await tuiRuntime.promptSecret("AgentMail API key", stdin, stdout);
+                if (value === null) {
+                    connectionNotice = "Key entry cancelled. Nothing was changed.";
+                    continue;
+                }
+                try {
+                    setUserKey("AGENTMAIL_API_KEY", value, sessionEnv);
+                    // Refresh only a value filled implicitly by discovery; explicit env/file wins.
+                    if (discoveredKeys.has("AGENTMAIL_API_KEY"))
+                        delete sessionEnv.AGENTMAIL_API_KEY;
+                    const saved = await saveCommsConnection(resolve(options.cwd));
+                    connectionNotice = saved.ok ? "Key stored. Project connection saved."
+                        : `Key stored for your user. ${saved.message}`;
+                    stdout.write("Checking AgentMail authentication…\n");
+                    connectionCheck = await tuiRuntime.checkComms({ cwd: resolve(options.cwd), env: connectionEnv(), online: true });
+                    connectionNotice = saved.ok
+                        ? connectionCheck.authenticated === true ? "Key stored. Authentication passed."
+                            : connectionCheck.authenticated === false ? "Key stored. Authentication rejected; test it for details."
+                                : "Key stored. Authentication unknown; test it to retry."
+                        : `${connectionNotice} ${connectionCheck.message}`;
+                }
+                catch {
+                    connectionNotice = "Could not store the key. Use a single non-empty line and check key-store permissions.";
+                }
+            }
         }
         finally {
             await observerSession.close();
@@ -681,7 +759,7 @@ function formatKeysHuman(result) {
     return `${lines.join("\n")}\n`;
 }
 /** Read one secret line: from a piped stdin when --stdin, else a hidden TTY prompt. */
-async function readSecretValue(useStdin, promptLabel, io) {
+async function readSecretValue(useStdin, promptLabel) {
     if (useStdin || !process.stdin.isTTY) {
         const chunks = [];
         for await (const chunk of process.stdin)
@@ -689,38 +767,7 @@ async function readSecretValue(useStdin, promptLabel, io) {
         const text = Buffer.concat(chunks).toString("utf8").trim();
         return text.length > 0 ? text : null;
     }
-    io.writeErr(`${promptLabel} (input hidden): `);
-    return await new Promise((resolve) => {
-        const stdin = process.stdin;
-        let value = "";
-        stdin.setRawMode?.(true);
-        stdin.resume();
-        stdin.setEncoding("utf8");
-        const onData = (key) => {
-            if (key === "\u0003") {
-                cleanup();
-                resolve(null);
-                return;
-            }
-            if (key === "\r" || key === "\n") {
-                cleanup();
-                io.writeErr("\n");
-                resolve(value.trim().length > 0 ? value.trim() : null);
-                return;
-            }
-            if (key === "\u007f" || key === "\b") {
-                value = value.slice(0, -1);
-                return;
-            }
-            value += key;
-        };
-        const cleanup = () => {
-            stdin.off("data", onData);
-            stdin.setRawMode?.(false);
-            stdin.pause();
-        };
-        stdin.on("data", onData);
-    });
+    return promptSecret(promptLabel, process.stdin, process.stderr);
 }
 function registerKeysCommand(parent, io) {
     const keys = parent
@@ -729,7 +776,7 @@ function registerKeysCommand(parent, io) {
         .summary("Manage the user-level provider key store.");
     keys
         .command("set")
-        .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github) or a raw ENV_NAME.")
+        .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME.")
         .description("Store one provider key in the user store (0600), prompted with hidden input.")
         .option("--stdin", "Read the value from stdin instead of prompting (for agents/pipes).")
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -739,13 +786,13 @@ function registerKeysCommand(parent, io) {
         if (name === null) {
             const result = {
                 schema: KEYS_RESULT_SCHEMA, ok: false, action: "set", store: storePath, names: [],
-                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github.`
+                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github, agentmail.`
             };
             writeResult(command, io, result, formatKeysHuman);
             io.setExitCode(2);
             return;
         }
-        const value = await readSecretValue(options.stdin === true, `Value for ${name}`, io);
+        const value = await readSecretValue(options.stdin === true, `Value for ${name}`);
         if (value === null) {
             const result = {
                 schema: KEYS_RESULT_SCHEMA, ok: false, action: "set", store: storePath, names: [name],
@@ -1140,8 +1187,113 @@ function registerRunsCommand(parent, io) {
 function registerCommsCommands(parent, io) {
     const comms = parent
         .command("comms")
-        .description("Off-app comms surfaces (email/SMS the app under test sends).")
+        .description("Local email capture, real receiving connections, checks and cleanup recovery.")
         .summary("Off-app comms surfaces.");
+    comms.command("providers")
+        .description("List installed communication provider capabilities. No network requests.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((_options, command) => {
+        const result = { schema: "humanish.comms-providers.v1", ok: true, providers: COMMS_PROVIDERS };
+        writeResult(command, io, result, () => COMMS_PROVIDERS.map(provider => `${provider.label}: ${provider.limitation}\nKey: ${provider.keyEnv}\nSetup: ${provider.setupUrl}\n`).join("\n"));
+    });
+    const connections = comms.command("connections").description("Manage project-local non-secret connection profiles. A lab explicitly selects its receiving connection.");
+    connections.command("list")
+        .description("Show saved connections and local credential status; does not authenticate with a provider.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load credentials for local status without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        if (!await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io }))
+            return;
+        const result = await readCommsSetup(resolve(options.cwd), process.env);
+        writeResult(command, io, result, value => `${value.message}\nAgentMail key: ${value.credential.present ? "present" : "missing"}\n${value.connections.map(connection => `${connection.name}: ${connection.provider} (${connection.apiKeyEnv})\n`).join("")}`);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    connections.command("add")
+        .argument("[name]", "Project connection name.", "agentmail")
+        .description("Save an AgentMail connection profile. Does not write a key, alter a lab or contact the provider.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--provider <id>", "Installed provider id.", "agentmail")
+        .option("--api-key-env <name>", "Environment variable NAME, never its value.", "AGENTMAIL_API_KEY")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (name, options, command) => {
+        const result = { schema: "humanish.comms-connection-result.v1", ...(options.provider === "agentmail"
+                ? await saveCommsConnection(resolve(options.cwd), name, options.apiKeyEnv)
+                : { ok: false, message: "Only AgentMail connection setup is currently available." }) };
+        writeResult(command, io, result, value => `${value.message}\n`);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    comms.command("check")
+        .description("Check connection and credential presence; --online authenticates without creating inboxes.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--connection <name>", "Saved connection name.", "agentmail")
+        .option("--lab <path>", "Check the connection selected by this exact lab.")
+        .option("--online", "Make a read-only provider authentication request.")
+        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        if (!await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io }))
+            return;
+        let connection = options.connection;
+        if (options.lab) {
+            const lab = await resolveLabManifest(options.cwd, options.lab);
+            if (!lab.ok || lab.config.comms?.email?.kind !== "real") {
+                const result = { ok: false, message: "This lab does not select a real email connection." };
+                writeResult(command, io, result, value => `${value.message}\n`);
+                io.setExitCode(2);
+                return;
+            }
+            connection = lab.config.comms.email.connection;
+        }
+        const result = await checkCommsConnection({ cwd: resolve(options.cwd), connection, env: process.env, online: options.online === true });
+        writeResult(command, io, result, value => `${value.message}\n`);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    comms.command("configure")
+        .description("Preview or save a local receiving-enabled copy of a supported lab. No provider requests.")
+        .requiredOption("--lab <path>", "Exact source lab path or handle.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--connection <name>", "Saved connection name.", "agentmail")
+        .option("--apply", "Save the local copy; original lab remains unchanged.")
+        .option("--plan-token <digest>", "Require the source and destination to match a previous preview.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const result = await configureCommsLab({ ...options, cwd: resolve(options.cwd) });
+        writeResult(command, io, result, value => `${value.message}\n`);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    comms.command("recover")
+        .description("Inspect interrupted email leases; --apply deletes only privately recorded resources owned by this project and account.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", "One run to inspect or recover.")
+        .option("--apply", "Recover the selected inactive run and verify mailbox deletion.")
+        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        if (!await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io }))
+            return;
+        const cwd = resolve(options.cwd);
+        try {
+            const entries = (await inspectCommsRecovery({ cwd })).filter(entry => !options.run || entry.runId === options.run);
+            if (!options.apply) {
+                const result = { schema: "humanish.comms-recovery.v1", ok: true, entries };
+                writeResult(command, io, result, value => value.entries.length ? value.entries.map(entry => `${entry.runId}: ${entry.unresolvedCount} unresolved; ${entry.activeOwner === null ? "unknown owner" : entry.activeOwner ? "active owner" : "inactive"}\n`).join("") : "No recoverable email leases in this project.\n");
+                return;
+            }
+            if (!options.run || entries.length !== 1)
+                throw new Error("selection");
+            const entry = entries[0];
+            const { connection, adapter } = await resolveReceivingConnection(cwd, entry.connectionName, process.env);
+            const result = { schema: "humanish.comms-recovery-result.v1", ...await recoverCommsReceiving({ cwd, runId: options.run, connectionName: entry.connectionName, apiKeyEnv: connection.apiKeyEnv, adapter }) };
+            writeResult(command, io, result, value => `${value.message}\n`);
+            io.setExitCode(result.ok ? 0 : 2);
+        }
+        catch {
+            const result = { schema: "humanish.comms-recovery-result.v1", ok: false, message: "Recovery could not complete. Select one recorded run with --run, check its connection, and retry. No unrecorded resources are eligible." };
+            writeResult(command, io, result, value => `${value.message}\n`);
+            io.setExitCode(2);
+        }
+    });
     comms
         .command("catch")
         .description("Run the email catch on THIS host so humanish can study an app it does not provision (#328). Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.")
@@ -3232,24 +3384,29 @@ async function renderAndMaybeFollowObserver(args) {
     }
 }
 async function applyEnvFileOption(args) {
+    const env = args.env ?? process.env;
     if (args.envFile) {
-        const result = await loadEnvFile(args.cwd, args.envFile);
+        const stagedEnv = { ...env };
+        const result = await loadEnvFile(args.cwd, args.envFile, stagedEnv);
         if (!result.ok) {
             writeResult(args.command, args.io, result, formatEnvFileHuman);
             args.io.setExitCode(2);
             return false;
         }
+        for (const name of result.loaded)
+            env[name] = stagedEnv[name];
     }
     // Provider-key discovery (#436): fill still-missing keys from the documented project
     // overlay, the owning vendors' native stores, and the humanish user store — fill-only
     // (an explicit --env-file or process env always wins), each fill announced by name and
     // source on stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
     try {
-        await keyDiscoveryFn({
+        const discovered = await keyDiscoveryFn({
             cwd: args.cwd,
-            env: process.env,
+            env,
             announce: (line) => args.io.writeErr(`${line}\n`)
         });
+        args.onDiscovered?.(discovered.map(fill => fill.name));
     }
     catch {
         // Discovery must never break a command; a rung that fails to read is a miss, not an error.