@bli-cockpit/cli 0.2.61 → 0.2.63

package/dist/commands/jarvis-turn.js

@@ -207,7 +207,15 @@ export async function sendOneTurn(context, prompt, io) {
         trace_failed: trace?.filter((step) => step.status === "failed").length ?? 0,
         model_requested: context.command.model ?? null,
         elapsed_ms: Date.now() - startedAt,
-        thread: context.command.thread === "main" ? "default" : "named",
+        // BLI-3786: `minted` is a conversation the DOOR opened for this call
+        // because nothing named one — read off the answer rather than guessed
+        // from the name, so this side keeps no copy of the server's rule. Never
+        // the thread name itself.
+        thread: body.thread && body.thread !== context.command.thread
+            ? "minted"
+            : context.command.thread === "main"
+                ? "default"
+                : "named",
         subject: context.command.subject ? "selected" : "caller",
         image_attached: attachment !== null,
         image_byte_size: attachment?.bytes.byteLength ?? null,
@@ -289,21 +297,28 @@ export async function readHistory(context, io) {
         writeThreadHistory(io, body);
     }
     else {
-        writeThreadList(io, body.threads ?? []);
+        writeThreadList(io, body.threads ?? [], body.agentThreads ?? 0);
     }
     writeLine(io.stderr, `[jarvis cli] history read ${JSON.stringify({
         mode: command.history ? "thread" : "threads",
         thread_count: body.threads?.length ?? null,
+        // BLI-3786: the per-call conversations a `--json` turn minted, folded
+        // out of the list by the door and counted here.
+        agent_thread_count: body.agentThreads ?? null,
         message_count: body.messages?.length ?? null,
         truncated: body.truncated ?? null,
     })}`);
     return 0;
 }
-function writeThreadList(io, threads) {
+function writeThreadList(io, threads, agentThreads) {
     if (threads.length === 0) {
         // A real answer, not a blank. Nothing here means nothing was ever asked
-        // from this terminal, which is worth saying rather than implying.
-        writeLine(io.stdout, "No terminal conversations yet. Ask something with `cockpit jarvis`.");
+        // from this terminal, which is worth saying rather than implying — and if
+        // the only conversations on this account were a program's, say THAT
+        // instead of "nothing was ever asked" (BLI-3786).
+        writeLine(io.stdout, agentThreads > 0
+            ? `No conversations you named yet — ${agentThreads} one-off ${agentThreads === 1 ? "conversation" : "conversations"} from \`--json\` turns are not listed. Ask something with \`cockpit jarvis\`.`
+            : "No terminal conversations yet. Ask something with `cockpit jarvis`.");
         return;
     }
     const styled = colorEnabled(io);
@@ -314,6 +329,10 @@ function writeThreadList(io, threads) {
             writeLine(io.stdout, dim(`  ${thread.preview}`, styled));
     }
     writeLine(io.stdout, "");
+    if (agentThreads > 0) {
+        // BLI-3786: never hidden without a number. Each one still replays by name.
+        writeLine(io.stdout, dim(`${agentThreads} one-off ${agentThreads === 1 ? "conversation" : "conversations"} from \`--json\` turns are not listed.`, styled));
+    }
     writeLine(io.stdout, dim("Replay one with `cockpit jarvis --thread <name> --history`.", styled));
 }
 function writeThreadHistory(io, body) {

package/dist/commands/local-args-tower-mail.js

@@ -0,0 +1,151 @@
+/**
+ * `cockpit mail` argument parsing (BLI-3708) — the mail surface's half of
+ * `local-args-tower.ts`, a sibling of `local-args-tower-work.ts` for the same
+ * reason that file is one: mail is its own noun with its own vocabulary (a
+ * mailbox, a thread, an attachment, a recipient), and folding it into another
+ * family's parser would stretch that family's doc comment past the truth.
+ *
+ * TWO SECRETS NEVER TRAVEL ON ARGV, and both are refused here rather than at
+ * the door:
+ *
+ * - **The app password.** `cockpit mail add-imap --address <a>` reads it from
+ *   STDIN, always. There is no `--password` flag to forget about: argv is
+ *   world-readable on a shared machine (`ps`), lands in shell history, and is
+ *   captured by this very product's own session harvester. That is the
+ *   sourcing-secrets verdict applied to the one credential this product
+ *   stores.
+ * - **The message body.** `cockpit mail send` takes it from stdin or
+ *   `--file`, the same discipline `cockpit issue comment` and `cockpit docs
+ *   update` keep.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const MAIL_ACTIONS = new Set([
+    "accounts",
+    "add-imap",
+    "detach",
+    "inbox",
+    "read",
+    "search",
+    "send",
+    "attachment",
+    "sync",
+]);
+/** Every verb that names ONE thing first: a thread, an attachment, a mailbox. */
+const MAIL_ACTIONS_NEEDING_A_SUBJECT = new Set(["read", "attachment", "detach", "sync"]);
+export function parseMailArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--account",
+            "--address",
+            "--name",
+            "--limit",
+            "--before",
+            "--unread",
+            "--label",
+            "--to",
+            "--cc",
+            "--subject",
+            "--reply-to",
+            "--file",
+            "--body-stdin",
+            "--out",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--account",
+            "--address",
+            "--name",
+            "--limit",
+            "--before",
+            "--label",
+            "--to",
+            "--cc",
+            "--subject",
+            "--reply-to",
+            "--file",
+            "--out",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "inbox" : first);
+    if (!MAIL_ACTIONS.has(action)) {
+        throw new Error(`Unknown mail command: ${first}. Try accounts, add-imap, detach, inbox, read, search, send, attachment, or sync.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let subject;
+    let query;
+    if (MAIL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
+        subject = optionalNonEmpty(rest[0]);
+        if (!subject) {
+            throw new Error(action === "read"
+                ? "mail read needs a thread id — take one from `cockpit mail inbox --json`."
+                : `mail ${action} needs an id.`);
+        }
+        if (rest.length > 1)
+            throw new Error(`mail ${action} takes one id, not ${rest.length}.`);
+    }
+    else if (action === "search") {
+        query = optionalNonEmpty(rest.join(" "));
+        if (!query)
+            throw new Error('mail search needs words: cockpit mail search "invoice from stripe".');
+    }
+    else if (rest.length > 0) {
+        throw new Error(`mail ${action} does not take "${rest[0]}".`);
+    }
+    const address = optionalNonEmpty(values.flags.get("--address"));
+    if (action === "add-imap" && !address) {
+        throw new Error("mail add-imap needs --address, and reads the app password from stdin.");
+    }
+    const to = splitAddresses(values.flags.get("--to"));
+    const cc = splitAddresses(values.flags.get("--cc"));
+    if (action === "send" && to.length === 0) {
+        throw new Error('mail send needs --to "someone@example.com" (comma-separated for several).');
+    }
+    if (action === "send" && !optionalNonEmpty(values.flags.get("--account"))) {
+        throw new Error("mail send needs --account <id>: with several mailboxes attached, which address this goes out from is yours to say. `cockpit mail accounts` lists them.");
+    }
+    const outPath = optionalNonEmpty(values.flags.get("--out"));
+    if (action === "attachment" && !outPath) {
+        throw new Error("mail attachment needs --out <path>: the file is written to disk, never to stdout.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && action !== "inbox" && action !== "search") {
+        throw new Error("--limit belongs to `cockpit mail inbox` or `cockpit mail search`.");
+    }
+    return {
+        kind: "mail",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(subject ? { subjectId: subject } : {}),
+        ...(query ? { query } : {}),
+        accountId: optionalNonEmpty(values.flags.get("--account")),
+        address,
+        displayName: optionalNonEmpty(values.flags.get("--name")),
+        ...(limit === undefined ? {} : { limit }),
+        before: optionalNonEmpty(values.flags.get("--before")),
+        unreadOnly: values.booleans.has("--unread"),
+        label: optionalNonEmpty(values.flags.get("--label")),
+        to,
+        cc,
+        subjectLine: optionalNonEmpty(values.flags.get("--subject")),
+        replyTo: optionalNonEmpty(values.flags.get("--reply-to")),
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        bodyStdin: values.booleans.has("--body-stdin"),
+        outPath,
+        json: values.booleans.has("--json"),
+    };
+}
+/** `a@x.com, b@y.com` → two recipients. Exact, never fuzzy; empties dropped. */
+function splitAddresses(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value !== "");
+}

package/dist/commands/local-args-tower.js

@@ -20,6 +20,7 @@
  *                                                      channels/messages (BLI-3706)
  *   local-args-tower-work.ts    issue, project     — the issue tracker
  *                                                      (BLI-3716)
+ *   local-args-tower-mail.ts    mail               — the mailboxes (BLI-3708)
  *   local-args-tower-search.ts   search            — one bar over all five
  *                                                      corpora (BLI-3728)
  *
@@ -30,4 +31,5 @@ export { parseBriefArgs, WORKBOOK_MIN_WIDTH, parseWorkbookArgs, parseNotesArgs,
 export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
-export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
+export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
+export { parseMailArgs } from "./local-args-tower-mail.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -103,6 +103,8 @@ export function parseLocalArgs(argv) {
             return parseMsgArgs(argv.slice(1));
         case "issue":
             return parseIssueArgs(argv.slice(1));
+        case "mail":
+            return parseMailArgs(argv.slice(1));
         case "project":
             return parseProjectArgs(argv.slice(1));
         case "search":

package/dist/commands/local-help-commands.js

@@ -253,7 +253,8 @@ export function localSubcommandHelp(command) {
                 "That object carries answer, sources (the Source: lines inside it), turn_id (pass it to --trace), thread_id (pass it to --thread), proposal_id (the coding-arm proposal this turn made, or null), degraded and degraded_reasons — the SAME shape the bli-tower MCP server's jarvis_ask tool returns, so a script and an agent read one contract. reply/thread/traceId/model/trace/latency are still there beside it and still mean what they always meant.",
                 "A turn that outlives the dashboard's own ceiling is reported as turn_timed_out — an incomplete answer is never printed as a finished one.",
                 "The command uses the existing paired device identity. It cannot override the caller, team, role, or person scope.",
-                "--threads lists the terminal conversations on this account; --thread <name> --history replays one (the newest --limit <n> messages). Neither takes a question, and neither can reach anybody else's conversations.",
+                "A thread is SINGLE-WRITER: two turns in the same conversation at the same time can read each other, and one can answer the other's question. Your own terminal is one conversation, named main, and stays that way. A --json turn is a program's, so it gets a FRESH conversation per call unless --thread names one, and the answer's thread_id is the name it used — pass that back with --thread to continue it deliberately. On a --json turn, --thread main asks for the shared default nobody chose, so it is treated as naming nothing and a fresh conversation is minted anyway.",
+                "--threads lists the terminal conversations on this account; --thread <name> --history replays one (the newest --limit <n> messages). The per-call conversations a --json turn minted are counted rather than listed, and any one of them still replays by name. Neither takes a question, and neither can reach anybody else's conversations.",
                 "--trace <id|last> prints the step tree of one turn — every model step, tool call and server-side memory step, with how long each took, which model ran it, the tokens it spent and what failed. `last` opens the turn this machine asked most recently. Like --threads it takes no question and reaches no model.",
                 "Run `cockpit login` first if this machine is not paired.",
             ],
@@ -595,6 +596,29 @@ export function localSubcommandHelp(command) {
                 "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
             ],
         ],
+        [
+            "mail",
+            [
+                "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
+                "",
+                "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
+                "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
+                "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
+                "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+                "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+                "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
+                "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
+                "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
+                "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
+                "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
+                "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
+                "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
+                "detach <account> — removes the mailbox, its stored mail and its credential.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
         [
             "project",
             [
@@ -617,7 +641,7 @@ export function localSubcommandHelp(command) {
                 "",
                 "The words are positional and do not need quoting unless they contain shell metacharacters:",
                 '`cockpit search storage ceiling` and `cockpit search "storage ceiling"` are the same search.',
-                "Quoted phrases and -word work inside the query itself \u2014 the query goes to Postgres\u2019s",
+                "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
                 "websearch parser, which shrugs at anything a person can type instead of raising.",
                 "",
                 "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
@@ -627,11 +651,11 @@ export function localSubcommandHelp(command) {
                 "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
                 "own database session, so a document or a channel you cannot open is not in the list.",
                 "",
-                "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" \u2014",
+                "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
                 "those are different facts and folding them together would let a broken search read as silence.",
                 "A memory result has no page to open; the text printed under it is the whole record.",
                 "",
-                "A refusal keeps Tower's own reason label \u2014 needs_rls_client, query_too_short, query_too_long,",
+                "A refusal keeps Tower's own reason label — needs_rls_client, query_too_short, query_too_long,",
                 "unknown_kind, read_failed.",
                 "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
             ],

package/dist/commands/local-help.js

@@ -45,6 +45,7 @@ export const rootCommandNames = new Set([
     "docs",
     "msg",
     "issue",
+    "mail",
     "project",
     "search",
     "release",
@@ -89,6 +90,7 @@ export function localCommandHelp(command) {
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+        "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",

package/dist/commands/local.js

@@ -35,6 +35,7 @@ import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
 import { runIssue } from "./issue.js";
+import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
 import { parseLocalArgs } from "./local-args.js";
@@ -142,6 +143,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMsg(command, io);
             case "issue":
                 return await runIssue(command, io);
+            case "mail":
+                return await runMail(command, io);
             case "project":
                 return await runProject(command, io);
             case "search":

package/dist/commands/mail.js

@@ -0,0 +1,337 @@
+/**
+ * `cockpit mail` — the mailboxes a person attached, from a terminal
+ * (BLI-3708).
+ *
+ * Nine verbs over `/api/mail/**`, the same doors the browser will use when the
+ * UI lands. Every one of those routes already accepts the collector device
+ * token (`resolveCaller({ allowDeviceToken: true })`), so this command is a
+ * terminal in front of an existing door and adds no authority of its own.
+ *
+ * The CLI is the FIRST surface for this wave, deliberately (AGENTS.md, "CLI is
+ * king"): a mailbox is easier to reason about as `--json` than as a rendered
+ * list, and every bug fixed here is fixed for the browser and MCP halves that
+ * share the same doors.
+ *
+ * TWO SECRETS NEVER TOUCH ARGV. `add-imap` reads the Google app password from
+ * STDIN and there is no flag that would take it; `send` reads the body from
+ * stdin or `--file`. `local-args-tower-mail.ts` says why in full.
+ *
+ * ONE MORE RULE, for the attachment verb: bytes go to a FILE, never to stdout.
+ * `--out` is required. A terminal that prints a PDF is a terminal somebody has
+ * to close, and `--json` output on stdout is a contract other tools parse.
+ */
+import { writeFile } from "node:fs/promises";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+import { towerRequest } from "../tower-client.js";
+const TAG = "[mail cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/** A sync pass reads a bounded page, but a cold mailbox can still take a while. */
+const SYNC_DEADLINE_MS = 120_000;
+const BODY_MAX_CHARS = 200_000;
+const PASSWORD_MAX_CHARS = 200;
+export async function runMail(command, io) {
+    const door = await openAgentDoor("mail", command, io);
+    switch (command.action) {
+        case "accounts":
+            return listAccounts(door);
+        case "add-imap":
+            return addImap(command, door);
+        case "detach":
+            return detach(command, door);
+        case "inbox":
+            return inbox(command, door);
+        case "read":
+            return readThread(command, door);
+        case "search":
+            return search(command, door);
+        case "send":
+            return send(command, door);
+        case "attachment":
+            return attachment(command, door);
+        case "sync":
+            return sync(command, door);
+    }
+}
+async function listAccounts(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/accounts",
+        method: "GET",
+        label: "mail accounts",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const accounts = answer.body.accounts ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, accounts });
+    if (accounts.length === 0) {
+        writeLine(door.io.stdout, "No mailboxes attached yet.");
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "A personal address:  cockpit mail add-imap --address you@gmail.com   (app password on stdin)");
+        writeLine(door.io.stdout, "A work address:      open Tower in a browser and connect Google.");
+        return 0;
+    }
+    for (const account of accounts) {
+        const health = account.status === "active" ? account.backfill_state : `${account.status}: ${account.status_reason ?? "no reason recorded"}`;
+        writeLine(door.io.stdout, `${account.address.padEnd(34)}  ${account.provider.padEnd(12)}  ${health.padEnd(18)}  ${account.last_sync_at ?? "never synced"}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${accounts.length} mailbox(es). ids: ${accounts.map((account) => account.id).join(", ")}`);
+    return 0;
+}
+async function addImap(command, door) {
+    // The password comes from stdin and nowhere else. An interactive terminal
+    // with nothing piped in is told how, rather than left waiting on a prompt
+    // that would echo the secret into the scrollback.
+    if (isInteractiveStdin(door.io)) {
+        return failAgentDoor(door, TAG, "password_required_on_stdin", 'The app password is read from stdin, never from a flag. Try: printf "%s" "abcd efgh ijkl mnop" | cockpit mail add-imap --address you@gmail.com');
+    }
+    let appPassword;
+    try {
+        appPassword = (await readPipedText(door.io.stdin, {
+            maxChars: PASSWORD_MAX_CHARS,
+            overflowMessage: "That does not look like a Google app password (they are 16 characters).",
+        })).trim();
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "password_unreadable", error instanceof Error ? error.message : String(error));
+    }
+    if (appPassword === "") {
+        return failAgentDoor(door, TAG, "password_required_on_stdin", "Nothing arrived on stdin, so nothing was attached.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/accounts",
+        method: "POST",
+        label: "mail add-imap",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            address: command.address,
+            display_name: command.displayName ?? null,
+            app_password: appPassword,
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const account = answer.body.account;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, account });
+    writeLine(door.io.stdout, `Attached ${account?.address ?? command.address} (${account?.id ?? "no id returned"}).`);
+    writeLine(door.io.stdout, "Nothing is read until a sync runs: `cockpit mail sync <id>`, or wait for the cron.");
+    return 0;
+}
+async function detach(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/accounts?account_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "DELETE",
+        label: "mail detach",
+        timeoutMs: WRITE_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, detached: command.subjectId });
+    writeLine(door.io.stdout, `Detached ${command.subjectId}. Its stored mail and its credential went with it.`);
+    return 0;
+}
+async function inbox(command, door) {
+    const query = new URLSearchParams();
+    if (command.accountId)
+        query.set("account_id", command.accountId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    if (command.before)
+        query.set("before", command.before);
+    if (command.unreadOnly)
+        query.set("unread", "1");
+    if (command.label)
+        query.set("label", command.label);
+    const suffix = query.toString();
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/inbox${suffix ? `?${suffix}` : ""}`,
+        method: "GET",
+        label: "mail inbox",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const messages = body.messages ?? [];
+    if (messages.length === 0) {
+        writeLine(door.io.stdout, (body.accounts ?? []).length === 0 ? "No mailboxes attached yet." : "No mail matches that.");
+        return 0;
+    }
+    for (const message of messages) {
+        writeLine(door.io.stdout, messageLine(message));
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${messages.length} message(s) across ${(body.accounts ?? []).length} mailbox(es).`);
+    return 0;
+}
+function messageLine(message) {
+    const flag = message.is_unread ? "*" : " ";
+    const paperclip = message.has_attachments ? "@" : " ";
+    const from = message.from_address?.address ?? "(no sender)";
+    const day = message.internal_date.slice(0, 16).replace("T", " ");
+    return `${flag}${paperclip} ${day}  ${from.padEnd(30).slice(0, 30)}  ${(message.subject ?? "(no subject)").slice(0, 60)}`;
+}
+async function readThread(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/threads/${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "GET",
+        label: "mail read",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, body.thread?.subject ?? "(no subject)");
+    writeLine(door.io.stdout, `${body.thread?.account_address ?? "?"} — ${body.messages?.length ?? 0} message(s)`);
+    for (const message of body.messages ?? []) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]`);
+        writeLine(door.io.stdout, (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim());
+    }
+    return 0;
+}
+async function search(command, door) {
+    const query = new URLSearchParams({ q: command.query ?? "" });
+    if (command.accountId)
+        query.set("account_id", command.accountId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/search?${query.toString()}`,
+        method: "GET",
+        label: "mail search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const matches = answer.body.matches ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, query: command.query, matches });
+    if (matches.length === 0) {
+        writeLine(door.io.stdout, `Nothing in your mail matched "${command.query}".`);
+        return 0;
+    }
+    for (const message of matches)
+        writeLine(door.io.stdout, messageLine(message));
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${matches.length} match(es).`);
+    return 0;
+}
+async function send(command, door) {
+    const body = await readBody(command, door);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "body_required", 'A message needs a body: `echo "on my way" | cockpit mail send --account <id> --to someone@example.com --subject "Re: lunch"`.');
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/mail/send",
+        method: "POST",
+        label: "mail send",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            account_id: command.accountId,
+            to: command.to.map((address) => ({ address })),
+            ...(command.cc.length > 0 ? { cc: command.cc.map((address) => ({ address })) } : {}),
+            subject: command.subjectLine ?? "",
+            text: body.text,
+            ...(command.replyTo ? { in_reply_to_message_id: command.replyTo } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const sent = answer.body.sent;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, sent });
+    writeLine(door.io.stdout, `Sent from ${sent?.address ?? "that mailbox"} to ${command.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`);
+    return 0;
+}
+async function attachment(command, door) {
+    const outPath = command.outPath;
+    // The bytes do not go through `askAgentDoor` — it parses JSON, and this
+    // response is a file. Same door, same token, raw response.
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: `/api/mail/attachments/${encodeURIComponent(command.subjectId ?? "")}`,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: "GET",
+        label: "mail attachment",
+        timeoutMs: WRITE_DEADLINE_MS,
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        return failAgentDoor(door, TAG, result.reason, result.detail);
+    }
+    if (!result.response.ok) {
+        return failAgentDoor(door, TAG, `http_${result.response.status}`, `Tower answered ${result.response.status} for that attachment. Nothing was written to ${outPath}.`);
+    }
+    const bytes = Buffer.from(await result.response.arrayBuffer());
+    try {
+        await writeFile(outPath, bytes);
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "write_failed", `Downloaded ${bytes.length} bytes and could not write them to ${outPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, path: outPath, bytes: bytes.length });
+    writeLine(door.io.stdout, `Wrote ${bytes.length} bytes to ${outPath}.`);
+    return 0;
+}
+async function sync(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/mail/accounts/${encodeURIComponent(command.subjectId ?? "")}/sync`,
+        method: "POST",
+        label: "mail sync",
+        timeoutMs: SYNC_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const run = answer.body.run;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, run });
+    if (!run) {
+        writeLine(door.io.stdout, "Tower answered without a run. Nothing to report.");
+        return 0;
+    }
+    if (run.reason === "ok") {
+        writeLine(door.io.stdout, `Synced: ${run.messagesAdded} new, ${run.messagesUpdated} updated, ${run.messagesDeleted} gone.`);
+        return 0;
+    }
+    // A failure names itself; the exit code says it failed.
+    writeLine(door.io.stderr, `${TAG} sync ${JSON.stringify({ reason: run.reason, detail: run.detail })}`);
+    writeLine(door.io.stdout, `That mailbox did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`);
+    return 1;
+}
+/** Body on stdin, never argv — `--file` is the safest way on Windows. */
+async function readBody(command, door) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(door.io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(door.io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `A message body is limited to ${BODY_MAX_CHARS} characters here.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "body_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.61");
+    writeLine(io?.stdout ?? process.stdout, "0.2.63");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.8",
-    "@bli-cockpit/mcp": "0.1.4",
+    "@bli-cockpit/mcp": "0.1.6",
     "@bli-cockpit/telemetry-core": "0.1.29"
   }
 }