@vellumai/cli 0.11.6 → 0.11.7-staging.1

package/src/commands/voice.ts

@@ -0,0 +1,370 @@
+/**
+ * `vellum voice [assistant]`
+ *
+ * Type a turn in the terminal, hear the assistant speak the reply.
+ *
+ * A real live-voice session that never opens a microphone: each typed line
+ * goes out as a `text` frame and joins the pipeline where a finished
+ * transcript would have, so the answer streams back through the same turn
+ * runner, the same segmented text-to-speech, and the same barge-in as a spoken
+ * turn. Ctrl+C mid-reply cuts the assistant off exactly as speaking over it
+ * would.
+ */
+
+import { createInterface, type Interface } from "node:readline";
+
+import chalk from "chalk";
+
+import { extractValueFlag } from "../lib/arg-utils.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { CliLiveVoiceClient } from "../lib/live-voice/client.js";
+import {
+  LiveVoiceConnectionError,
+  resolveLiveVoiceConnection,
+} from "../lib/live-voice/connection.js";
+import { PcmPlayer } from "../lib/live-voice/pcm-player.js";
+import { MAX_TEXT_TURN_CHARS } from "../lib/live-voice/protocol.js";
+
+function printUsage(): void {
+  console.log(`vellum voice - Talk to an assistant by typing; hear it answer
+
+USAGE:
+    vellum voice [assistant] [options]
+
+ARGUMENTS:
+    [assistant]    Instance name or ID (default: active assistant)
+
+OPTIONS:
+    --conversation <id>  Continue an existing conversation instead of starting one
+    --no-audio           Print replies without speaking them
+    --help               Show this help
+
+DESCRIPTION:
+    Opens a live-voice session with no microphone. Each line you type is
+    taken as a turn and the reply is streamed back as text and spoken aloud.
+    A turn is at most ${MAX_TEXT_TURN_CHARS} characters.
+
+    Speech needs a PCM player on PATH. ffplay, play (sox), or aplay stream the
+    audio as it arrives; afplay (macOS) plays each reply once it is complete.
+    With none of them installed the session still runs, printed but silent.
+
+    Ctrl+C interrupts the assistant mid-reply. Ctrl+D, or Ctrl+C when nothing
+    is being spoken, ends the session.
+
+    Local and self-hosted assistants only. Vellum cloud assistants authenticate
+    with a session token, which the voice endpoint does not accept.
+
+EXAMPLES:
+    vellum voice
+    vellum voice my-assistant
+    vellum voice my-assistant --no-audio
+    vellum voice --conversation conv_01H8XK3
+`);
+}
+
+export async function voice(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  // Strips `--conversation <id>` from argv, rejecting a `-`-prefixed value:
+  // the daemon accepts any non-empty conversation id, so a swallowed option
+  // would open a conversation named after the flag it ate.
+  const conversationId = extractValueFlag(args, "conversation");
+  const assistantArg = parseAssistantTargetArg(args);
+  const audioEnabled = !args.includes("--no-audio");
+
+  let connection;
+  try {
+    connection = await resolveLiveVoiceConnection(assistantArg);
+  } catch (err) {
+    if (err instanceof LiveVoiceConnectionError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const player = audioEnabled ? new PcmPlayer() : null;
+  const client = new CliLiveVoiceClient({
+    url: connection.url,
+    token: connection.token,
+    ...(conversationId ? { conversationId } : {}),
+  });
+
+  await runSession({ client, player, reference: connection.reference });
+}
+
+interface SessionDeps {
+  client: CliLiveVoiceClient;
+  player: PcmPlayer | null;
+  reference: string;
+}
+
+/**
+ * Drive one session to completion.
+ *
+ * Resolves when the socket closes, whether that is the user leaving or a
+ * failure. The exit code is set on the way out rather than thrown, so a failed
+ * session prints one line instead of a stack.
+ */
+function runSession({ client, player, reference }: SessionDeps): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let rl: Interface | null = null;
+    // True from the moment a turn is sent until its reply has been spoken.
+    // The daemon refuses a second turn while one is in flight, so the prompt
+    // is withheld for exactly as long.
+    let turnInFlight = false;
+    /**
+     * The in-flight turn's server-side id, once a frame has named it.
+     *
+     * Matches a completion frame to the turn it belongs to, so one that
+     * arrives late cannot end a turn it does not describe. Null while the turn
+     * is still anonymous, in which case a completion frame is taken at face
+     * value: there is nothing to contradict it.
+     */
+    let activeTurnId: string | null = null;
+    // Whether anything of this turn's reply has been printed yet, so the
+    // speaker label is written once rather than per delta.
+    let replyStarted = false;
+    let lastActivity = "";
+    let finished = false;
+
+    const finish = (error?: string): void => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      player?.dispose();
+      rl?.close();
+      if (error) {
+        console.error(`\n${chalk.red("Error:")} ${error}`);
+        process.exitCode = 1;
+      }
+      resolve();
+    };
+
+    /** Hand the prompt back and let the user take another turn. */
+    const endTurn = (note?: string): void => {
+      // `finished` matters as much as `turnInFlight`: a session that closed
+      // while a `finish()` was still awaited resolves it through dispose(),
+      // and the prompt must not be redrawn under a closed interface.
+      if (!turnInFlight || finished) {
+        return;
+      }
+      turnInFlight = false;
+      activeTurnId = null;
+      replyStarted = false;
+      lastActivity = "";
+      if (note) {
+        process.stdout.write(chalk.dim(note));
+      }
+      process.stdout.write("\n");
+      rl?.resume();
+      rl?.prompt();
+    };
+
+    /**
+     * Whether a completion frame belongs to the turn currently in flight.
+     *
+     * A turn abandoned locally (Ctrl+C) leaves the prompt free while the
+     * daemon may still be winding down, so a late frame must not be allowed to
+     * end whatever turn came after it.
+     */
+    const completesActiveTurn = (turnId: string): boolean =>
+      turnInFlight && (activeTurnId === null || activeTurnId === turnId);
+
+    client.on("ready", (frame) => {
+      if (!client.supportsTextInput) {
+        // The `ready` echo is the only reliable signal. A daemon that predates
+        // typed turns answers every `text` frame with `unknown_type`, so
+        // opening the prompt anyway would give the user a session that
+        // silently swallows everything they type.
+        finish(
+          `${reference} does not accept typed turns. Upgrade it with ` +
+            `'vellum upgrade' and try again.`,
+        );
+        client.end();
+        return;
+      }
+
+      console.log(
+        chalk.dim(`Connected to ${reference}. ${describePlayback(player)}.`),
+      );
+      if (!client.hasAudioInput) {
+        // Expected here rather than alarming: this client declared it can type,
+        // which is what let the session open text-only instead of being refused.
+        console.log(
+          chalk.dim(
+            "Speech-to-text is not configured on this assistant, so typed turns only.",
+          ),
+        );
+      }
+      console.log(
+        chalk.dim(
+          "Type a message and press enter. Ctrl+C interrupts, Ctrl+D exits.",
+        ),
+      );
+      console.log(`Conversation: ${chalk.dim(frame.conversationId)}\n`);
+
+      rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: chalk.cyan("> "),
+      });
+
+      rl.on("line", (line) => {
+        const text = line.trim();
+        if (text.length === 0) {
+          rl?.prompt();
+          return;
+        }
+        if (text.length > MAX_TEXT_TURN_CHARS) {
+          console.error(
+            chalk.yellow(
+              `Too long: ${text.length} characters, limit is ${MAX_TEXT_TURN_CHARS}.`,
+            ),
+          );
+          rl?.prompt();
+          return;
+        }
+        if (turnInFlight) {
+          console.error(chalk.yellow("Still replying. Ctrl+C to interrupt."));
+          return;
+        }
+        if (!client.sendText(text)) {
+          console.error(
+            chalk.yellow("Message not sent, the session is closed."),
+          );
+          return;
+        }
+        turnInFlight = true;
+        activeTurnId = null;
+        // Withhold the prompt until the reply lands, so the next line the user
+        // types is not composed against a turn the daemon would refuse.
+        rl?.pause();
+      });
+
+      rl.on("SIGINT", () => {
+        if (!turnInFlight) {
+          client.end();
+          return;
+        }
+        // Barge-in. The turn ends here rather than on a frame from the daemon,
+        // because a client `interrupt` is answered with neither `tts_done` nor
+        // `turn_cancelled`: the daemon's `interrupt()` cancels the turn through
+        // `cancelAssistantTurn`, `tts_done` is gated on the turn not being
+        // aborted, and `turn_cancelled` is only sent down the VAD barge-in
+        // path. Waiting for one would hang the prompt for the rest of the
+        // session.
+        client.interrupt();
+        player?.stop();
+        endTurn(" [interrupted]");
+      });
+
+      rl.on("close", () => {
+        // Ctrl+D at the prompt. `end()` is idempotent, so this is also the
+        // path taken when finish() closed the interface itself.
+        client.end();
+      });
+
+      rl.prompt();
+    });
+
+    client.on("activity", (frame) => {
+      activeTurnId = frame.turnId;
+      // Only worth showing while the turn is still silent. Once text is
+      // streaming, the reply itself is the better progress indicator.
+      if (replyStarted || frame.label === "" || frame.label === lastActivity) {
+        return;
+      }
+      lastActivity = frame.label;
+      console.log(chalk.dim(`  ... ${frame.label}`));
+    });
+
+    client.on("textDelta", (frame) => {
+      if (!replyStarted) {
+        replyStarted = true;
+        process.stdout.write(chalk.green("< "));
+      }
+      process.stdout.write(frame.text);
+    });
+
+    client.on("audio", (frame) => {
+      if (!player) {
+        return;
+      }
+      player.write(Buffer.from(frame.dataBase64, "base64"), frame.sampleRate);
+    });
+
+    client.on("turnDone", (turnId) => {
+      if (!completesActiveTurn(turnId)) {
+        // Still drain the audio: the frame is stale for the prompt's purposes
+        // but the bytes are real and already queued.
+        void player?.finish();
+        return;
+      }
+      // The turn is not over until the speaker is quiet. Handing the prompt
+      // back at the last byte instead would make Ctrl+C quit the session while
+      // the assistant is still talking, and let the next turn start a second
+      // player over the top of the first.
+      void player?.finish().then(() => endTurn());
+    });
+
+    client.on("turnCancelled", (turnId) => {
+      // Audio still in flight belongs to a turn that no longer exists.
+      player?.stop();
+      if (completesActiveTurn(turnId)) {
+        endTurn(" [interrupted]");
+      }
+    });
+
+    client.on("textTurnRejected", (reason, message) => {
+      console.error(
+        chalk.yellow(
+          reason === "unsupported"
+            ? `Typed turns are not supported by this assistant: ${message}`
+            : `Turn not taken: ${message}`,
+        ),
+      );
+      player?.stop();
+      endTurn();
+    });
+
+    client.on("warning", (message) => {
+      console.error(chalk.yellow(`Warning: ${message}`));
+    });
+
+    client.on("closed", (error) => {
+      if (!error) {
+        console.log(chalk.dim("\nSession ended."));
+      }
+      finish(error);
+    });
+
+    client.connect();
+  });
+}
+
+/**
+ * How this session will (or will not) speak, for the connection banner.
+ *
+ * The two silent cases are worth telling apart: a user who passed --no-audio
+ * knows why it is quiet, and a user who did not needs to be told that
+ * installing a player is what turns the sound on.
+ */
+function describePlayback(player: PcmPlayer | null): string {
+  if (!player) {
+    return "Audio off (--no-audio)";
+  }
+  switch (player.mode) {
+    case "streaming":
+      return `Speaking via ${player.playerName}`;
+    case "buffered":
+      return `Speaking via ${player.playerName}, one reply at a time`;
+    case "silent":
+      return "Silent: install ffplay, sox, or aplay to hear replies";
+  }
+}

package/src/components/DefaultMainScreen.tsx

@@ -163,12 +163,6 @@ interface SubmitDecisionResponse {
   accepted: boolean;
 }
 
-interface AddTrustRuleResponse {
-  accepted: boolean;
-}
-
-type TrustDecision = "always_allow" | "always_deny";
-
 interface HealthResponse {
   status: string;
   message?: string;
@@ -375,27 +369,6 @@ async function submitDecision(
   );
 }
 
-async function addTrustRule(
-  baseUrl: string,
-  assistantId: string,
-  requestId: string,
-  pattern: string,
-  scope: string,
-  decision: "allow" | "deny",
-  auth?: Record<string, string>,
-): Promise<AddTrustRuleResponse> {
-  return runtimeRequest<AddTrustRuleResponse>(
-    baseUrl,
-    assistantId,
-    "/trust-rules",
-    {
-      method: "POST",
-      body: JSON.stringify({ requestId, pattern, scope, decision }),
-    },
-    auth,
-  );
-}
-
 // ── SSE event types ─────────────────────────────────────────────
 interface SseEvent {
   type: string;
@@ -568,8 +541,6 @@ async function handleConfirmationPrompt(
     confirmation.toolName,
     confirmation.input,
   );
-  const allowlistOptions = confirmation.allowlistOptions ?? [];
-
   chatApp.addStatus(`\u250C ${confirmation.toolName}: ${preview}`);
   chatApp.addStatus(`\u2502 Risk: ${confirmation.riskLevel}`);
   if (confirmation.executionTarget) {
@@ -578,12 +549,6 @@ async function handleConfirmationPrompt(
   chatApp.addStatus("\u2514");
 
   const options = ["Allow once", "Deny once"];
-  if (
-    allowlistOptions.length > 0 &&
-    confirmation.persistentDecisionsAllowed !== false
-  ) {
-    options.push("Allowlist...", "Denylist...");
-  }
 
   const index = await chatApp.showSelection("Tool Approval", options);
 
@@ -592,115 +557,6 @@ async function handleConfirmationPrompt(
     chatApp.addStatus("\u2714 Allowed", "green");
     return;
   }
-  if (index === 2) {
-    await handlePatternSelection(
-      baseUrl,
-      assistantId,
-      requestId,
-      confirmation,
-      chatApp,
-      "always_allow",
-      auth,
-    );
-    return;
-  }
-  if (index === 3) {
-    await handlePatternSelection(
-      baseUrl,
-      assistantId,
-      requestId,
-      confirmation,
-      chatApp,
-      "always_deny",
-      auth,
-    );
-    return;
-  }
-
-  await submitDecision(baseUrl, assistantId, requestId, "deny", auth);
-  chatApp.addStatus("\u2718 Denied", "yellow");
-}
-
-async function handlePatternSelection(
-  baseUrl: string,
-  assistantId: string,
-  requestId: string,
-  confirmation: PendingConfirmation,
-  chatApp: ChatAppHandle,
-  trustDecision: TrustDecision,
-  auth?: Record<string, string>,
-): Promise<void> {
-  const allowlistOptions = confirmation.allowlistOptions ?? [];
-  const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
-  const options = allowlistOptions.map((o) => o.label);
-
-  const index = await chatApp.showSelection(
-    `${label}: choose command pattern`,
-    options,
-  );
-
-  if (index >= 0 && index < allowlistOptions.length) {
-    const selectedPattern = allowlistOptions[index].pattern;
-    await handleScopeSelection(
-      baseUrl,
-      assistantId,
-      requestId,
-      confirmation,
-      chatApp,
-      selectedPattern,
-      trustDecision,
-      auth,
-    );
-    return;
-  }
-
-  await submitDecision(baseUrl, assistantId, requestId, "deny", auth);
-  chatApp.addStatus("\u2718 Denied", "yellow");
-}
-
-async function handleScopeSelection(
-  baseUrl: string,
-  assistantId: string,
-  requestId: string,
-  confirmation: PendingConfirmation,
-  chatApp: ChatAppHandle,
-  selectedPattern: string,
-  trustDecision: TrustDecision,
-  auth?: Record<string, string>,
-): Promise<void> {
-  const scopeOptions = confirmation.scopeOptions ?? [];
-  const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
-  const options = scopeOptions.map((o) => o.label);
-
-  const index = await chatApp.showSelection(`${label}: choose scope`, options);
-
-  if (index >= 0 && index < scopeOptions.length) {
-    const ruleDecision = trustDecision === "always_deny" ? "deny" : "allow";
-    await addTrustRule(
-      baseUrl,
-      assistantId,
-      requestId,
-      selectedPattern,
-      scopeOptions[index].scope,
-      ruleDecision,
-      auth,
-    );
-    await submitDecision(
-      baseUrl,
-      assistantId,
-      requestId,
-      ruleDecision === "deny" ? "deny" : "allow",
-      auth,
-    );
-    const ruleLabel =
-      trustDecision === "always_deny" ? "Denylisted" : "Allowlisted";
-    const ruleColor = trustDecision === "always_deny" ? "yellow" : "green";
-    chatApp.addStatus(
-      `${trustDecision === "always_deny" ? "\u2718" : "\u2714"} ${ruleLabel}`,
-      ruleColor,
-    );
-    return;
-  }
 
   await submitDecision(baseUrl, assistantId, requestId, "deny", auth);
   chatApp.addStatus("\u2718 Denied", "yellow");

package/src/index.ts

@@ -37,6 +37,7 @@ import { tunnel } from "./commands/tunnel";
 import { unpair } from "./commands/unpair";
 import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
+import { voice } from "./commands/voice";
 import { wake } from "./commands/wake";
 import { workflows } from "./commands/workflows";
 import { resolveAssistant, setActiveAssistant } from "./lib/assistant-config";
@@ -76,6 +77,7 @@ const commands = {
   unpair,
   upgrade,
   use,
+  voice,
   wake,
   whoami,
   workflows,
@@ -92,7 +94,7 @@ function printHelp(): void {
   console.log("  client   Connect to a hatched assistant");
   console.log("  confirm  Resolve a pending tool confirmation on an assistant");
   console.log(
-    "  connect  Import an assistant paired from another machine [beta]",
+    "  connect  Pair with an assistant running on another machine [beta]",
   );
   console.log(
     "  devices  List or revoke devices paired to a local assistant [beta]",
@@ -108,7 +110,7 @@ function printHelp(): void {
   console.log("  logout   Log out of the Vellum platform");
   console.log("  message  Send a message to a running assistant");
   console.log(
-    "  pair     Mint a device-scoped token to connect another machine [beta]",
+    "  pair     Print a pairing link and QR code for another device [beta]",
   );
   console.log(
     "  ps       List assistants (or processes for a specific assistant)",
@@ -131,6 +133,7 @@ function printHelp(): void {
   );
   console.log("  upgrade  Upgrade an assistant to a newer version");
   console.log("  use      Set the active assistant for commands");
+  console.log("  voice    Type to an assistant and hear it answer out loud");
   console.log("  wake     Start the assistant and gateway");
   console.log("  whoami   Show current logged-in user");
   console.log("  workflows Inspect and control workflow runs");

package/src/lib/detached-process.ts

@@ -0,0 +1,81 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { closeSync } from "node:fs";
+import { join } from "node:path";
+
+import { isCompiledCli } from "./local.js";
+import { getLogDir, openLogFile, resetLogFile } from "./xdg-log.js";
+
+export interface RelaunchDetachedOptions {
+  /** argv for the re-invoked CLI command, e.g. ["tunnel", "--provider", "ngrok"]. */
+  args: string[];
+  /** Log file basename under the XDG log dir; truncated before spawn. */
+  logFile: string;
+  /**
+   * Polled (with the resolved log path) until it resolves truthy, the child
+   * exits, or timeoutMs elapses.
+   */
+  isReady: (logPath: string) => Promise<boolean> | boolean;
+  timeoutMs: number;
+  pollIntervalMs?: number;
+}
+
+export interface DetachedRelaunchResult {
+  child: ChildProcess;
+  logPath: string;
+  /** True once `isReady` returned truthy before the child exited or the timeout elapsed. */
+  ready: boolean;
+  /** The child's exit code, or `null` for a spawn error. Undefined while still running. */
+  exitCode: number | null | undefined;
+}
+
+/**
+ * Re-invoke the current CLI binary with `args` as a detached background
+ * process, redirecting stdout/stderr to `logFile` in the XDG log dir, then
+ * poll `isReady` until it succeeds, the child exits, or `timeoutMs` elapses.
+ *
+ * Shared by every command that offers a detached/background mode (e.g.
+ * `vellum tunnel -d`, `vellum client --interface web --background`) so the
+ * spawn/log/poll mechanics live in one place; each caller supplies its own
+ * readiness check and decides how to react to a timeout or early exit.
+ */
+export async function relaunchDetached(
+  opts: RelaunchDetachedOptions,
+): Promise<DetachedRelaunchResult> {
+  const spawnArgs = isCompiledCli()
+    ? opts.args
+    : [process.argv[1], ...opts.args];
+
+  resetLogFile(opts.logFile);
+  const fd = openLogFile(opts.logFile);
+  const child = spawn(process.execPath, spawnArgs, {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  if (typeof fd === "number") {
+    closeSync(fd);
+  }
+  child.unref();
+
+  const logPath = join(getLogDir(), opts.logFile);
+
+  let exitCode: number | null | undefined;
+  child.on("error", () => {
+    exitCode = null;
+  });
+  child.on("exit", (code) => {
+    exitCode = code;
+  });
+
+  const deadline = Date.now() + opts.timeoutMs;
+  const pollIntervalMs = opts.pollIntervalMs ?? 250;
+  let ready = false;
+  while (Date.now() < deadline && exitCode === undefined) {
+    if (await opts.isReady(logPath)) {
+      ready = true;
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  return { child, logPath, ready, exitCode };
+}