humanish 0.95.0 → 0.96.0

package/dist/program.d.ts

@@ -1,6 +1,7 @@
 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";
@@ -40,6 +41,7 @@ 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;

package/dist/program.js

@@ -11,6 +11,9 @@ 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";
@@ -463,6 +466,7 @@ function registerDoctorCommand(parent, io) {
     });
 }
 const defaultTuiRuntime = {
+    checkComms: checkCommsConnection,
     promptSecret,
     stdin: process.stdin,
     stdout: process.stdout,
@@ -645,6 +649,7 @@ function registerTuiCommand(parent, io) {
         const observerSession = createTuiObserverSession(resolve(options.cwd));
         let exitCode = 0;
         let connectionNotice;
+        let connectionCheck;
         try {
             for (;;) {
                 const outcome = await loaded.startTui({
@@ -653,8 +658,21 @@ function registerTuiCommand(parent, io) {
                     version: { cli: CLI_VERSION },
                     capabilities: {
                         comms: {
-                            read: () => readCommsSetup(resolve(options.cwd), connectionEnv()),
-                            save: () => saveCommsConnection(resolve(options.cwd))
+                            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." };
+                                }
+                            }
                         },
                         // 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.
@@ -708,6 +726,13 @@ function registerTuiCommand(parent, io) {
                     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.";
@@ -1162,7 +1187,7 @@ function registerRunsCommand(parent, io) {
 function registerCommsCommands(parent, io) {
     const comms = parent
         .command("comms")
-        .description("Email capture and communication connection setup.")
+        .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.")
@@ -1171,7 +1196,7 @@ function registerCommsCommands(parent, io) {
         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. Setup does not enable email receiving.");
+    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.", ".")
@@ -1198,6 +1223,77 @@ function registerCommsCommands(parent, io) {
         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.")