@vellumai/assistant 0.8.4 → 0.8.6

package/src/cli/commands/channels/index.ts

@@ -0,0 +1,229 @@
+/**
+ * `assistant channels` — inspect messaging channels.
+ *
+ *   list                     — overview of every channel + ready state
+ *   get <channel>            — detailed live snapshot of a single channel
+ *
+ * `get` always re-runs remote probes (it invalidates the readiness cache
+ * before reading), so the CLI answer matches the live source-of-truth.
+ *
+ * A mutating `refresh` verb (for reconnecting channels — e.g. supplying
+ * fresh Slack tokens) is intentionally not shipped here; it will land in
+ * its own PR.
+ */
+
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+// ---------------------------------------------------------------------------
+// Snapshot shape (mirrors runtime/routes/channel-readiness-routes.ts)
+// ---------------------------------------------------------------------------
+
+interface ReadinessCheck {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+interface ChannelSnapshot {
+  channel: string;
+  ready: boolean;
+  setupStatus: "not_configured" | "incomplete" | "ready";
+  checkedAt: number;
+  stale: boolean;
+  reasons: Array<{ code: string; text: string }>;
+  localChecks: ReadinessCheck[];
+  remoteChecks?: ReadinessCheck[];
+  channelHandle?: unknown;
+}
+
+interface ReadinessResponse {
+  success: boolean;
+  snapshots: ChannelSnapshot[];
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+function statusGlyph(s: ChannelSnapshot): string {
+  if (s.ready) return "✅";
+  if (s.setupStatus === "not_configured") return "○ ";
+  return "⚠️ ";
+}
+
+function statusWord(s: ChannelSnapshot): string {
+  if (s.ready) return "ready";
+  if (s.setupStatus === "not_configured") return "not configured";
+  return "incomplete";
+}
+
+function renderList(snapshots: ChannelSnapshot[]): void {
+  const sorted = [...snapshots].sort((a, b) =>
+    a.channel.localeCompare(b.channel),
+  );
+  log.info("Channel        Status");
+  log.info("-------------  ------");
+  for (const s of sorted) {
+    log.info(`${statusGlyph(s)} ${s.channel.padEnd(12)}  ${statusWord(s)}`);
+  }
+}
+
+function renderSnapshot(s: ChannelSnapshot): void {
+  log.info(`${statusGlyph(s)} ${s.channel} — ${s.setupStatus}`);
+  if (s.reasons.length > 0) {
+    log.info("");
+    log.info("Reasons:");
+    for (const r of s.reasons) {
+      log.info(`  • [${r.code}] ${r.text}`);
+    }
+  }
+  if (s.localChecks.length > 0) {
+    log.info("");
+    log.info("Local checks:");
+    for (const c of s.localChecks) {
+      log.info(`  ${c.passed ? "✓" : "✗"} ${c.name} — ${c.message}`);
+    }
+  }
+  if (s.remoteChecks && s.remoteChecks.length > 0) {
+    log.info("");
+    log.info("Remote checks:");
+    for (const c of s.remoteChecks) {
+      log.info(`  ${c.passed ? "✓" : "✗"} ${c.name} — ${c.message}`);
+    }
+  }
+}
+
+/** All channel IDs the readiness service knows about. Mirrors channels/types.ts. */
+const KNOWN_CHANNELS = [
+  "telegram",
+  "phone",
+  "vellum",
+  "whatsapp",
+  "slack",
+  "email",
+  "platform",
+  "a2a",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerChannelsCommand(program: Command): void {
+  registerCommand(program, {
+    name: "channels",
+    transport: "ipc",
+    description:
+      "Inspect and repair messaging channels (slack, telegram, email, etc.)",
+    build: (channels) => {
+      channels.addHelpText(
+        "after",
+        `
+Channels are the messaging surfaces the assistant talks over — slack,
+telegram, whatsapp, email, phone, vellum, platform, a2a. Each channel
+has a probe that reports whether it's configured and reachable.
+
+  list                    Overview of every channel + ready state
+  get <channel>           Live snapshot of one channel (always re-probes)
+
+Examples:
+  $ assistant channels list
+  $ assistant channels get slack`,
+      );
+
+      // -----------------------------------------------------------------------
+      // list
+      // -----------------------------------------------------------------------
+
+      channels
+        .command("list")
+        .description("Show readiness state for every configured channel")
+        .option("--json", "Machine-readable compact JSON output")
+        .option(
+          "--remote",
+          "Include remote checks (live network round-trip per channel)",
+          false,
+        )
+        .action(
+          async (
+            opts: { json?: boolean; remote?: boolean },
+            cmd: Command,
+          ) => {
+            const r = await cliIpcCall<ReadinessResponse>(
+              "channels_readiness_get",
+              {
+                queryParams: {
+                  includeRemote: opts.remote ? "true" : "false",
+                },
+              },
+            );
+            if (!r.ok) {
+              return exitFromIpcResult(
+                { ok: false, error: r.error, statusCode: r.statusCode },
+                cmd,
+              );
+            }
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, { snapshots: r.result!.snapshots });
+            } else {
+              renderList(r.result!.snapshots);
+            }
+          },
+        );
+
+      // -----------------------------------------------------------------------
+      // get — always live (invalidates cache + re-runs remote checks)
+      // -----------------------------------------------------------------------
+
+      channels
+        .command("get")
+        .description(
+          "Live readiness snapshot for one channel (always re-probes; no caching)",
+        )
+        .argument(
+          "<channel>",
+          `Channel id: ${KNOWN_CHANNELS.join(", ")}`,
+        )
+        .option("--json", "Machine-readable compact JSON output")
+        .action(
+          async (
+            channel: string,
+            _opts: { json?: boolean },
+            cmd: Command,
+          ) => {
+            // `get` is always live: invalidate the cache and re-run remote
+            // checks. This matches what source code does when it needs to
+            // know the channel's current state — no stale snapshots.
+            const r = await cliIpcCall<ReadinessResponse>(
+              "channels_readiness_refresh_post",
+              { body: { channel, includeRemote: true } },
+            );
+            if (!r.ok) {
+              return exitFromIpcResult(
+                { ok: false, error: r.error, statusCode: r.statusCode },
+                cmd,
+              );
+            }
+            const snapshot = r.result!.snapshots.find(
+              (s) => s.channel === channel,
+            );
+            if (!snapshot) {
+              log.error(`No readiness probe registered for channel: ${channel}`);
+              process.exitCode = 1;
+              return;
+            }
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, snapshot);
+            } else {
+              renderSnapshot(snapshot);
+            }
+          },
+        );
+    },
+  });
+}

package/src/cli/commands/domain.ts

@@ -38,12 +38,17 @@ for email and web presence. DNS managed by the Vellum platform.
 
 Examples:
   $ assistant domain register velly
+  $ assistant domain register velly --email-username hello
   $ assistant domain register --json
-  $ assistant domain status`,
+  $ assistant domain status velly`,
       );
 
       domain
         .command("register [subdomain]")
+        .option(
+          "--email-username <username>",
+          "Also register an email address (e.g. --email-username hello → hello@<subdomain>.domain)",
+        )
         .description(
           `Register a custom subdomain on ${baseDomain} for this assistant`,
         )
@@ -54,6 +59,10 @@ Arguments:
   subdomain   The subdomain to register (e.g. "velly" → velly.${baseDomain}).
               If omitted, the platform derives it from the assistant's name.
 
+Options:
+  --email-username <username>  Also register an email address for the domain
+                               (e.g. --email-username hello → hello@velly.${baseDomain})
+
 Registers a subdomain at <subdomain>.${baseDomain}. DNS managed by the
 Vellum platform — no manual DNS changes needed.
 
@@ -61,27 +70,36 @@ Examples:
   $ assistant domain register velly
   ✓ Registered velly.${baseDomain}
 
+  $ assistant domain register velly --email-username hello
+  ✓ Registered velly.${baseDomain} (email: hello@velly.${baseDomain})
+
   $ assistant domain register
   ✓ Registered my-assistant.${baseDomain}
 
   $ assistant domain register velly --json
-  {"domain":"velly.${baseDomain}","id":"...","status":"active","verified":true}`,
+  {"domain":"velly.${baseDomain}","id":"..."}`,
         )
         .action(
-          async (subdomain: string | undefined, _opts: unknown, cmd: Command) => {
+          async (
+            subdomain: string | undefined,
+            opts: { emailUsername?: string },
+            cmd: Command,
+          ) => {
             const body: Record<string, string> = {};
             if (subdomain) {
               body.subdomain = subdomain;
             }
+            if (opts.emailUsername) {
+              body.email_username = opts.emailUsername;
+            }
 
             const r = await cliIpcCall<{
               id: string;
               subdomain?: string;
               domain?: string;
-              status?: string;
-              verified?: boolean;
               created_at?: string;
               created?: string;
+              email_error?: { detail: string; code: string };
             }>("domain_register", { body });
 
             if (!r.ok)
@@ -104,10 +122,16 @@ Examples:
             if (shouldOutputJson(cmd)) {
               writeOutput(cmd, data);
             } else {
-              log.info(`✓ Registered ${displayDomain}`);
-              if (data.verified === false) {
+              if (opts.emailUsername && !data.email_error) {
                 log.info(
-                  "  ⚠ Domain verification pending — this usually resolves within a few seconds.",
+                  `✓ Registered ${displayDomain} (email: ${opts.emailUsername}@${displayDomain})`,
+                );
+              } else {
+                log.info(`✓ Registered ${displayDomain}`);
+              }
+              if (data.email_error) {
+                log.warn(
+                  `⚠ Email registration failed: ${data.email_error.detail}`,
                 );
               }
             }
@@ -115,32 +139,35 @@ Examples:
         );
 
       domain
-        .command("status")
-        .description("Show this assistant's domain registration and health")
+        .command("status <subdomain>")
+        .description(
+          "Show registration and DNS verification status for a subdomain",
+        )
         .addHelpText(
           "after",
           `
-Shows the domain currently registered for this assistant, including
-verification status and DNS health.
+Arguments:
+  subdomain   The subdomain to check (e.g. "velly").
+
+Shows the domain's registration details and live DNS verification
+status from the email provider.
 
 Examples:
-  $ assistant domain status
-  Domain:   velly.${baseDomain}
-  Status:   active
-  Verified: yes
-  Created:  2026-04-15
-
-  $ assistant domain status --json
-  {"domain":"velly.${baseDomain}","status":"active","verified":true,...}`,
+  $ assistant domain status velly
+  Domain:       velly.${baseDomain}
+  Verification: verified
+                DNS records have been verified. Your domain is ready to send and receive email.
+  Created:      2026-04-15
+
+  $ assistant domain status velly --json
+  {"domain":{"subdomain":"velly","id":"..."},"verification":{"status":"verified","message":"..."}}`,
         )
-        .action(async (_opts: unknown, cmd: Command) => {
+        .action(async (subdomain: string, _opts: unknown, cmd: Command) => {
           const r = await cliIpcCall<{
             results: {
               id: string;
               subdomain?: string;
               domain?: string;
-              status?: string;
-              verified?: boolean;
               created_at?: string;
               created?: string;
             }[];
@@ -154,28 +181,51 @@ Examples:
 
           const data = r.result!;
           const domains = data.results ?? [];
+          const d = domains.find(
+            (entry) => entry.subdomain === subdomain,
+          );
+
+          if (!d) {
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, { error: `Domain "${subdomain}" not found` });
+              process.exitCode = 1;
+            } else {
+              log.error(
+                `Domain "${subdomain}" is not registered for this assistant.`,
+              );
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          // Fetch live verification status
+          const v = await cliIpcCall<{
+            domain: string;
+            status: string;
+            message: string;
+          }>("domain_verification_status", {
+            body: { domain_id: d.id },
+          });
+
+          const verification = v.ok ? v.result : undefined;
 
           if (shouldOutputJson(cmd)) {
-            writeOutput(cmd, data);
-          } else if (domains.length === 0) {
-            log.info(
-              "No domain registered for this assistant. Run: assistant domain register [subdomain]",
-            );
+            writeOutput(cmd, { domain: d, verification: verification ?? null });
           } else {
-            for (const d of domains) {
-              const displayDomain =
-                d.domain ??
-                (d.subdomain ? `${d.subdomain}.${apexDomain}` : "unknown");
-              const createdRaw = d.created_at ?? d.created;
-              const createdDate = createdRaw
-                ? createdRaw.split("T")[0]
-                : "unknown";
-              log.info(`Domain:   ${displayDomain}`);
-              if (d.status != null) log.info(`Status:   ${d.status}`);
-              if (d.verified != null)
-                log.info(`Verified: ${d.verified ? "yes" : "no"}`);
-              log.info(`Created:  ${createdDate}`);
+            const displayDomain =
+              d.domain ??
+              (d.subdomain ? `${d.subdomain}.${apexDomain}` : "unknown");
+            const createdRaw = d.created_at ?? d.created;
+            const createdDate = createdRaw
+              ? createdRaw.split("T")[0]
+              : "unknown";
+            log.info(`Domain:       ${displayDomain}`);
+            const vStatus = verification?.status ?? "unknown";
+            log.info(`Verification: ${vStatus}`);
+            if (verification?.message) {
+              log.info(`              ${verification.message}`);
             }
+            log.info(`Created:      ${createdDate}`);
           }
         });
     },

package/src/cli/commands/inference.ts

@@ -30,6 +30,54 @@ interface InferenceSendResult {
   };
 }
 
+const DEFAULT_INFERENCE_IPC_TIMEOUT_MS = 32 * 60 * 1000;
+const MAX_TIMER_TIMEOUT_MS = 2_147_483_647;
+const MAX_INFERENCE_TIMEOUT_SECONDS = Math.floor(MAX_TIMER_TIMEOUT_MS / 1000);
+
+function parsePositiveIntegerOption(
+  raw: string | undefined,
+  flagName: string,
+  options: { max?: number } = {},
+): { ok: true; value: number | undefined } | { ok: false; error: string } {
+  if (raw === undefined) {
+    return { ok: true, value: undefined };
+  }
+
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return {
+      ok: false,
+      error: `Invalid ${flagName} value. Must be a positive integer.`,
+    };
+  }
+
+  const value = Number(trimmed);
+  if (
+    !Number.isSafeInteger(value) ||
+    value < 1 ||
+    (options.max !== undefined && value > options.max)
+  ) {
+    return {
+      ok: false,
+      error:
+        `Invalid ${flagName} value. Must be a positive integer` +
+        (options.max !== undefined ? ` no greater than ${options.max}` : "") +
+        ".",
+    };
+  }
+
+  return { ok: true, value };
+}
+
+function writeCliError(message: string, jsonOutput?: boolean): void {
+  if (jsonOutput) {
+    process.stdout.write(JSON.stringify({ ok: false, error: message }) + "\n");
+  } else {
+    log.error(message);
+  }
+  process.exitCode = 1;
+}
+
 // ── Send subcommand ──────────────────────────────────────────────────
 
 /**
@@ -47,6 +95,11 @@ function attachSendSubcommand(group: Command): void {
       "Apply a named inference profile from llm.profiles for this single call",
     )
     .option("--max-tokens <n>", "Max response tokens", undefined)
+    .option(
+      "--timeout-seconds <seconds>",
+      "Maximum time to wait for the inference response",
+      undefined,
+    )
     .option("--json", "Output structured JSON")
     .argument("[message...]", "User message (joined with spaces)")
     .addHelpText(
@@ -59,12 +112,15 @@ Behavioral notes:
     only. It does NOT open a session — to pin a profile to a conversation,
     use 'assistant inference profile open <name>'.
   - --profile layers below --model: --model still wins on the model field.
+  - Long-running requests wait up to 32 minutes by default. Use
+    --timeout-seconds to adjust the wait budget for this call.
   - Requires a configured LLM provider (see 'assistant config set').
 
 Examples:
   $ assistant inference send "What is 2+2?"
   $ echo "Summarize this" | assistant inference send
   $ assistant llm send --system-prompt "You are a poet" "Write a haiku"
+  $ assistant inference send --timeout-seconds 300 "Draft a long memo"
   $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
   $ assistant inference send --profile balanced "Explain RFC 1149"`,
     )
@@ -76,30 +132,37 @@ Examples:
           model?: string;
           profile?: string;
           maxTokens?: string;
+          timeoutSeconds?: string;
           json?: boolean;
         },
       ) => {
         const { systemPrompt, model, profile, json: jsonOutput } = opts;
-        const maxTokens = opts.maxTokens
-          ? parseInt(opts.maxTokens, 10)
-          : undefined;
-
-        if (
-          opts.maxTokens !== undefined &&
-          (!Number.isFinite(maxTokens) || maxTokens! < 1)
-        ) {
-          const msg = "Invalid --max-tokens value. Must be a positive integer.";
-          if (jsonOutput) {
-            process.stdout.write(
-              JSON.stringify({ ok: false, error: msg }) + "\n",
-            );
-          } else {
-            log.error(msg);
-          }
-          process.exitCode = 1;
+        const parsedMaxTokens = parsePositiveIntegerOption(
+          opts.maxTokens,
+          "--max-tokens",
+        );
+        const parsedTimeoutSeconds = parsePositiveIntegerOption(
+          opts.timeoutSeconds,
+          "--timeout-seconds",
+          { max: MAX_INFERENCE_TIMEOUT_SECONDS },
+        );
+
+        if (!parsedMaxTokens.ok) {
+          writeCliError(parsedMaxTokens.error, jsonOutput);
+          return;
+        }
+
+        if (!parsedTimeoutSeconds.ok) {
+          writeCliError(parsedTimeoutSeconds.error, jsonOutput);
           return;
         }
 
+        const maxTokens = parsedMaxTokens.value;
+        const timeoutMs =
+          parsedTimeoutSeconds.value !== undefined
+            ? parsedTimeoutSeconds.value * 1000
+            : DEFAULT_INFERENCE_IPC_TIMEOUT_MS;
+
         // Determine user message: positional args or stdin.
         let messageText = messageParts.length > 0 ? messageParts.join(" ") : "";
 
@@ -114,14 +177,7 @@ Examples:
         if (!messageText) {
           const msg =
             "No message provided. Pass a message as an argument or pipe via stdin.";
-          if (jsonOutput) {
-            process.stdout.write(
-              JSON.stringify({ ok: false, error: msg }) + "\n",
-            );
-          } else {
-            log.error(msg);
-          }
-          process.exitCode = 1;
+          writeCliError(msg, jsonOutput);
           return;
         }
 
@@ -135,17 +191,14 @@ Examples:
         const ipcResult = await cliIpcCall<InferenceSendResult>(
           "inference_send",
           { body },
+          { timeoutMs },
         );
 
         if (!ipcResult.ok) {
-          if (jsonOutput) {
-            process.stdout.write(
-              JSON.stringify({ ok: false, error: ipcResult.error }) + "\n",
-            );
-          } else {
-            log.error(ipcResult.error ?? "Unknown error occurred");
-          }
-          process.exitCode = 1;
+          writeCliError(
+            ipcResult.error ?? "Unknown error occurred",
+            jsonOutput,
+          );
           return;
         }
 
@@ -179,9 +232,9 @@ export function registerInferenceCommand(program: Command): void {
     transport: "ipc",
     description: "LLM inference operations",
     build: (inference) => {
-  inference.addHelpText(
-    "after",
-    `
+      inference.addHelpText(
+        "after",
+        `
 The inference command group sends requests to your configured LLM provider.
 The provider is resolved from your assistant config (llm.default.provider).
 
@@ -191,11 +244,11 @@ Examples:
   $ assistant llm send --system-prompt "Be concise" "What is TCP?"
   $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
   $ assistant inference send --profile balanced "Explain RFC 1149"`,
-  );
+      );
 
-  attachSendSubcommand(inference);
-  attachSessionSubcommand(inference);
-  attachProvidersSubcommand(inference);
+      attachSendSubcommand(inference);
+      attachSessionSubcommand(inference);
+      attachProvidersSubcommand(inference);
     },
   });