@vellumai/cli 0.11.7-staging.2 → 0.11.8-staging.1

package/src/commands/voice.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+
+import { CliLiveVoiceClient } from "../lib/live-voice/client.js";
+
+import { runSession } from "./voice.js";
+
+/**
+ * Minimal stand-in for the WebSocket the client drives, matching the fake in
+ * `lib/live-voice/client.test.ts`. `runSession` is exercised through a real
+ * `CliLiveVoiceClient` rather than a hand-rolled fake client, because the
+ * client has private fields and cannot be satisfied structurally.
+ */
+class FakeSocket {
+  static readonly OPEN = 1;
+  binaryType = "arraybuffer";
+  readyState = 0;
+  readonly sent: string[] = [];
+  closed = false;
+
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: unknown }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: ((event: { code: number; reason: string }) => void) | null = null;
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  open(): void {
+    this.readyState = FakeSocket.OPEN;
+    this.onopen?.();
+  }
+
+  deliver(frame: unknown): void {
+    this.onmessage?.({ data: JSON.stringify(frame) });
+  }
+}
+
+const READY = {
+  type: "ready",
+  seq: 1,
+  sessionId: "sess_1",
+  conversationId: "conv_1",
+  textInput: true,
+};
+
+describe("runSession --say", () => {
+  test("ends the session after turnDone even with no player (--no-audio)", async () => {
+    const socket = new FakeSocket();
+    const client = new CliLiveVoiceClient({
+      url: "ws://127.0.0.1:7830/v1/live-voice",
+      token: "guardian-token",
+      webSocketFactory: () => socket as unknown as WebSocket,
+    });
+
+    // player: null is what `--no-audio` passes. Before the fix, `turnDone`'s
+    // `player?.finish().then(...)` short-circuited entirely on a null player,
+    // so `endTurn()` (and therefore `client.end()`) never ran and the session
+    // hung forever with the socket still open. This test hangs on that
+    // regression rather than failing fast, which is exactly the bug: the
+    // suite's own timeout is what would catch it.
+    const sessionDone = runSession({
+      client,
+      player: null,
+      reference: "test-assistant (asst_1)",
+      sayText: "hello",
+    });
+
+    socket.open();
+    socket.deliver(READY);
+    socket.deliver({ type: "tts_done", seq: 2, turnId: "turn_1" });
+
+    await sessionDone;
+
+    expect(socket.closed).toBe(true);
+  });
+});

package/src/commands/voice.ts

@@ -36,6 +36,8 @@ ARGUMENTS:
 
 OPTIONS:
     --conversation <id>  Continue an existing conversation instead of starting one
+    --say <message>      Take this one turn, speak the reply, then exit. For
+                         scripts and triggers: no prompt, no terminal needed.
     --no-audio           Print replies without speaking them
     --help               Show this help
 
@@ -51,11 +53,13 @@ DESCRIPTION:
     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.
+    Works with local, self-hosted, and Vellum cloud assistants. A cloud
+    assistant needs a platform login ('vellum login'); the session is
+    authorized per-connection from it.
 
 EXAMPLES:
     vellum voice
+    vellum voice my-assistant --say "i just got back to my desk"
     vellum voice my-assistant
     vellum voice my-assistant --no-audio
     vellum voice --conversation conv_01H8XK3
@@ -73,9 +77,23 @@ export async function voice(): Promise<void> {
   // 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");
+  // One turn, then exit. Extracted before the assistant target is parsed so a
+  // multi-word message is never mistaken for a display name.
+  const sayText = extractValueFlag(args, "say");
   const assistantArg = parseAssistantTargetArg(args);
   const audioEnabled = !args.includes("--no-audio");
 
+  if (sayText !== undefined && sayText.trim().length === 0) {
+    console.error("Error: --say needs a message.");
+    process.exit(1);
+  }
+  if (sayText !== undefined && sayText.length > MAX_TEXT_TURN_CHARS) {
+    console.error(
+      `Error: --say is ${sayText.length} characters, limit is ${MAX_TEXT_TURN_CHARS}.`,
+    );
+    process.exit(1);
+  }
+
   let connection;
   try {
     connection = await resolveLiveVoiceConnection(assistantArg);
@@ -91,16 +109,33 @@ export async function voice(): Promise<void> {
   const client = new CliLiveVoiceClient({
     url: connection.url,
     token: connection.token,
+    tokenTransport: connection.tokenTransport,
     ...(conversationId ? { conversationId } : {}),
   });
 
-  await runSession({ client, player, reference: connection.reference });
+  await runSession({
+    client,
+    player,
+    reference: connection.reference,
+    ...(sayText !== undefined ? { sayText } : {}),
+  });
 }
 
-interface SessionDeps {
+/** Exported for tests. Not part of the command's public surface. */
+export interface SessionDeps {
   client: CliLiveVoiceClient;
   player: PcmPlayer | null;
   reference: string;
+  /**
+   * Take this one turn and exit, instead of opening a prompt.
+   *
+   * The session ends only once the reply has finished *speaking*, which is why
+   * this cannot be approximated by piping a line into the interactive prompt:
+   * stdin reaches EOF the instant the line is read, readline closes, and the
+   * session is torn down while the turn is still in flight. That race is
+   * winnable on a fast local assistant and reliably lost over velay.
+   */
+  sayText?: string;
 }
 
 /**
@@ -110,7 +145,12 @@ interface SessionDeps {
  * 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> {
+export function runSession({
+  client,
+  player,
+  reference,
+  sayText,
+}: 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.
@@ -162,6 +202,14 @@ function runSession({ client, player, reference }: SessionDeps): Promise<void> {
         process.stdout.write(chalk.dim(note));
       }
       process.stdout.write("\n");
+      if (sayText !== undefined) {
+        // The reply has been spoken to the end (`turnDone` waits on the
+        // player before calling this), so there is nothing left to stay open
+        // for. Ending here also frees the assistant's single live-voice slot
+        // rather than holding it for a timeout to reclaim.
+        client.end();
+        return;
+      }
       rl?.resume();
       rl?.prompt();
     };
@@ -177,6 +225,29 @@ function runSession({ client, player, reference }: SessionDeps): Promise<void> {
       turnInFlight && (activeTurnId === null || activeTurnId === turnId);
 
     client.on("ready", (frame) => {
+      if (sayText !== undefined) {
+        if (!client.supportsTextInput) {
+          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)}.`),
+        );
+        console.log(`Conversation: ${chalk.dim(frame.conversationId)}\n`);
+        if (!client.sendText(sayText)) {
+          finish("Message not sent, the session is closed.");
+          client.end();
+          return;
+        }
+        turnInFlight = true;
+        activeTurnId = null;
+        return;
+      }
+
       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
@@ -310,7 +381,13 @@ function runSession({ client, player, reference }: SessionDeps): Promise<void> {
       // 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());
+      //
+      // `player` is null under `--no-audio`, and optional chaining on its own
+      // would short-circuit the whole expression in that case, skipping
+      // `.then()` and leaving `endTurn()` uncalled. `?? Promise.resolve()`
+      // keeps a promise on the left of `.then` either way, so the turn always
+      // ends whether or not there is a player to wait on.
+      void (player?.finish() ?? Promise.resolve()).then(() => endTurn());
     });
 
     client.on("turnCancelled", (turnId) => {

package/src/commands/wake.ts

@@ -17,6 +17,7 @@ import {
   waitForDaemonMigrationsReady,
 } from "../lib/http-client.js";
 import {
+  DAEMON_STOP_TIMEOUT_MS,
   isProcessAlive,
   resolveProcessState,
   stopProcessByPidFile,
@@ -149,7 +150,12 @@ export async function wake(): Promise<void> {
       console.log(
         `Assistant running (pid ${daemonState.pid}) — restarting in watch mode...`,
       );
-      const stopped = await stopProcessByPidFile(pidFile, "assistant");
+      const stopped = await stopProcessByPidFile(
+        pidFile,
+        "assistant",
+        undefined,
+        DAEMON_STOP_TIMEOUT_MS,
+      );
       if (!stopped && isProcessAlive(pidFile).alive) {
         daemonRunning = true;
         daemonUnready = true;

package/src/lib/assistant-client.ts

@@ -1,8 +1,8 @@
 /**
  * Gateway client for authenticated requests to a hatched assistant's runtime.
  *
- * Encapsulates lockfile reading, guardian-token resolution, and
- * authenticated fetch so callers can simply do:
+ * Encapsulates lockfile reading, credential resolution, and authenticated
+ * fetch so callers can simply do:
  *
  * ```ts
  * const client = new AssistantClient();                          // active / latest
@@ -10,6 +10,11 @@
  * await client.get("/healthz");
  * await client.post("/messages/", { content: "hi" });
  * ```
+ *
+ * The auth scheme follows the assistant's topology, so callers never pick it.
+ * Platform-managed entries in particular have no local guardian token: they
+ * authenticate against the wildcard runtime proxy at
+ * `{platformUrl}/v1/assistants/<id>/<rest>` with the stored platform credential.
  */
 
 import { resolveAssistant } from "./assistant-config.js";
@@ -20,10 +25,25 @@ import {
   guardianTokenDueForRenewal,
 } from "./guardian-token.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import {
+  authHeaders,
+  invalidateOrgIdCache,
+  readPlatformToken,
+} from "./platform-client.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
 
+/**
+ * - `guardian`: `Authorization: Bearer <guardian JWT>`, refreshable on a 401.
+ * - `session`: caller-supplied `X-Session-Token` + explicit org id.
+ * - `platform`: `cloud: "vellum"` entry; headers resolved lazily from the
+ *   stored platform token (org id needs a network lookup).
+ */
+type AuthMode = "guardian" | "session" | "platform";
+
+const stripTrailingSlashes = (url: string): string => url.replace(/\/+$/, "");
+
 export interface AssistantClientOpts {
   assistantId?: string;
   runtimeUrl?: string;
@@ -32,6 +52,9 @@ export interface AssistantClientOpts {
    * session token instead of a guardian token.  The session token is
    * sent as `X-Session-Token: <sessionToken>` and the org id is
    * sent via the `Vellum-Organization-Id` header.
+   *
+   * Platform-managed assistants do NOT need this: they are detected from the
+   * lockfile entry and authenticated from the stored platform token.
    */
   sessionToken?: string;
   /** Required when `sessionToken` is provided. */
@@ -49,11 +72,16 @@ export class AssistantClient {
   readonly runtimeUrl: string;
 
   private readonly _assistantId: string;
-  /** Mutable: a 401 on the guardian path refreshes this in place (see request). */
+  /**
+   * The credential for the current mode. Mutable: a 401 on the guardian path
+   * refreshes it in place (see request), and the platform path fills it in on
+   * first use (see resolveAuthHeaders).
+   */
   private token: string | undefined;
-  /** True when token is a platform session token (X-Session-Token), false for guardian JWT (Authorization: Bearer). */
-  private readonly isSessionAuth: boolean;
+  private readonly authMode: AuthMode;
   private readonly orgId: string | undefined;
+  /** Cached in-flight/resolved platform auth headers; cleared to force a re-resolve. */
+  private platformHeaders: Promise<Record<string, string>> | undefined;
 
   /**
    * Resolves an assistant entry from the lockfile and loads auth credentials.
@@ -73,27 +101,108 @@ export class AssistantClient {
       );
     }
 
-    this.runtimeUrl = (
-      opts?.runtimeUrl ||
-      entry.localUrl ||
-      entry.runtimeUrl ||
-      FALLBACK_RUNTIME_URL
-    ).replace(/\/+$/, "");
     this._assistantId = entry.assistantId;
+    const platformManaged = !opts?.sessionToken && entry.cloud === "vellum";
+    const platformHost = stripTrailingSlashes(entry.runtimeUrl);
+
+    // SECURITY: a platform credential is account-scoped, far broader than the
+    // per-assistant guardian JWT, so its origin is pinned to the host recorded in
+    // the lockfile. Honoring a URL override here would hand the caller's session
+    // token or `vak_` key to whatever host they named.
+    if (
+      platformManaged &&
+      opts?.runtimeUrl &&
+      stripTrailingSlashes(opts.runtimeUrl) !== platformHost
+    ) {
+      throw new Error(
+        `Refusing to send platform credentials to '${opts.runtimeUrl}': ` +
+          `assistant '${entry.assistantId}' is hosted at ${platformHost}.`,
+      );
+    }
+
+    this.runtimeUrl = platformManaged
+      ? platformHost
+      : stripTrailingSlashes(
+          opts?.runtimeUrl ||
+            entry.localUrl ||
+            entry.runtimeUrl ||
+            FALLBACK_RUNTIME_URL,
+        );
 
     if (opts?.sessionToken) {
-      // Platform assistant: use X-Session-Token + Vellum-Organization-Id.
+      // Caller supplied the credential: X-Session-Token + Vellum-Organization-Id.
       this.token = opts.sessionToken;
-      this.isSessionAuth = true;
+      this.authMode = "session";
       this.orgId = opts.orgId;
+    } else if (platformManaged) {
+      // Platform-managed: no guardian token exists locally, so authenticate with
+      // the stored platform credential. Resolved on first use because the org id
+      // behind it needs a network lookup.
+      this.token = undefined;
+      this.authMode = "platform";
+      this.orgId = undefined;
     } else {
       this.token =
         loadGuardianToken(this._assistantId)?.accessToken ?? entry.bearerToken;
-      this.isSessionAuth = false;
+      this.authMode = "guardian";
       this.orgId = undefined;
     }
   }
 
+  /**
+   * Platform token for a `cloud: "vellum"` entry. Throws the actionable login
+   * error rather than letting an anonymous request fall through to a bare 403.
+   */
+  private requirePlatformToken(): string {
+    const token = readPlatformToken();
+    if (!token) {
+      throw new Error(
+        "Not logged in. Run `vellum login` first to authenticate with the platform.",
+      );
+    }
+    return token;
+  }
+
+  /**
+   * Auth headers for the current mode. `authHeaders` picks the right scheme for
+   * the platform credential (`Authorization: Bearer` for `vak_` API keys,
+   * `X-Session-Token` + `Vellum-Organization-Id` for session tokens) and caches
+   * the org-id lookup, so the result is memoized per client and a failure is
+   * never cached.
+   */
+  private async resolveAuthHeaders(): Promise<Record<string, string>> {
+    if (this.authMode !== "platform") {
+      const headers: Record<string, string> = {};
+      if (this.token) {
+        if (this.authMode === "session") {
+          headers["X-Session-Token"] = this.token;
+        } else {
+          headers["Authorization"] = `Bearer ${this.token}`;
+        }
+      }
+      if (this.orgId) {
+        headers["Vellum-Organization-Id"] = this.orgId;
+      }
+      return headers;
+    }
+
+    if (!this.platformHeaders) {
+      this.token = this.requirePlatformToken();
+      this.platformHeaders = authHeaders(this.token, this.runtimeUrl)
+        .then((resolved) => {
+          // request() owns Content-Type (bodyless requests must not carry one).
+          const headers = { ...resolved };
+          delete headers["Content-Type"];
+          return headers;
+        })
+        .catch((err: unknown) => {
+          this.platformHeaders = undefined;
+          throw err;
+        });
+    }
+    return this.platformHeaders;
+  }
+
   /** GET request to the gateway. Auth headers are added automatically. */
   async get(urlPath: string, opts?: RequestOpts): Promise<Response> {
     return this.request("GET", urlPath, undefined, opts);
@@ -185,17 +294,13 @@ export class AssistantClient {
     const jsonBody = body !== undefined ? JSON.stringify(body) : undefined;
 
     // Headers are built per-attempt so a refreshed token is picked up on retry.
-    const buildHeaders = (): Record<string, string> => {
+    // Caller-supplied headers win over the resolved auth headers.
+    const buildHeaders = async (): Promise<Record<string, string>> => {
       const headers: Record<string, string> = { ...opts?.headers };
-      if (this.token) {
-        if (this.isSessionAuth) {
-          headers["X-Session-Token"] ??= this.token;
-        } else {
-          headers["Authorization"] ??= `Bearer ${this.token}`;
-        }
-      }
-      if (this.orgId) {
-        headers["Vellum-Organization-Id"] ??= this.orgId;
+      for (const [name, value] of Object.entries(
+        await this.resolveAuthHeaders(),
+      )) {
+        headers[name] ??= value;
       }
       if (body !== undefined) {
         headers["Content-Type"] = "application/json";
@@ -203,8 +308,8 @@ export class AssistantClient {
       return headers;
     };
 
-    const doFetch = (): Promise<Response> => {
-      const headers = buildHeaders();
+    const doFetch = async (): Promise<Response> => {
+      const headers = await buildHeaders();
       if (opts?.signal) {
         return loopbackSafeFetch(url, {
           method,
@@ -226,11 +331,20 @@ export class AssistantClient {
 
     const response = await doFetch();
 
-    // Reactive auto-refresh on a 401 for the guardian (non-session) path.
-    // Ephemeral (`--token`) and access-only sessions have no stored refresh
-    // credential and just see the original 401; the platform session-auth path
-    // is never refreshed here (its token is managed by the Vellum platform).
-    if (response.status === 401 && !this.isSessionAuth) {
+    // A stale cached Vellum-Organization-Id is the usual cause of a 401 on the
+    // platform path (e.g. the user switched orgs elsewhere). Drop it and retry
+    // once. Mirrors localRuntimeIdentity in local-runtime-client.ts.
+    if (response.status === 401 && this.authMode === "platform" && this.token) {
+      invalidateOrgIdCache(this.token, this.runtimeUrl);
+      this.platformHeaders = undefined;
+      return doFetch();
+    }
+
+    // Reactive auto-refresh on a 401 for the guardian path only. Ephemeral
+    // (`--token`) and access-only sessions have no stored refresh credential and
+    // just see the original 401; session and platform credentials are managed by
+    // the Vellum platform and are never refreshed here.
+    if (response.status === 401 && this.authMode === "guardian") {
       const stored = loadGuardianToken(this._assistantId);
 
       // Another process may have already rotated and persisted a fresh access

package/src/lib/cloudflare-tunnel.ts

@@ -24,6 +24,7 @@ export function getCloudflareTunnelVersion(): string | null {
       encoding: "utf-8",
       timeout: 5_000,
       stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
     });
     return output.trim();
   } catch {
@@ -41,7 +42,7 @@ export function startCloudflareTunnelProcess(targetPort: number): ChildProcess {
     "cloudflared",
     ["tunnel", "--url", `http://localhost:${targetPort}`, "--no-autoupdate"],
     // Keep stdio as pipes so we can parse the URL from output.
-    { stdio: ["ignore", "pipe", "pipe"] },
+    { stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
   );
 }
 

package/src/lib/detached-process.ts

@@ -50,6 +50,7 @@ export async function relaunchDetached(
   const child = spawn(process.execPath, spawnArgs, {
     detached: true,
     stdio: ["ignore", fd, fd],
+    windowsHide: true,
   });
   if (typeof fd === "number") {
     closeSync(fd);

package/src/lib/guardian-token.ts

@@ -77,7 +77,7 @@ function getMacOSPlatformUUID(): string | null {
   try {
     const output = execSync(
       "ioreg -rd1 -c IOPlatformExpertDevice | awk '/IOPlatformUUID/{print $3}'",
-      { encoding: "utf-8", timeout: 5000 },
+      { encoding: "utf-8", timeout: 5000, windowsHide: true },
     ).trim();
     const uuid = output.replace(/"/g, "");
     return uuid.length > 0 ? uuid : null;
@@ -316,7 +316,9 @@ function isUnreachableGatewayError(error: unknown): boolean {
   );
 }
 
-function classifyRefreshThrownError(error: unknown): GuardianTokenRefreshResult {
+function classifyRefreshThrownError(
+  error: unknown,
+): GuardianTokenRefreshResult {
   if (isTimeoutLikeError(error)) {
     return {
       ok: false,

package/src/lib/hatch-local.ts

@@ -227,7 +227,11 @@ export async function hatchLocal(
         }
       }
 
-      if (!apiKeyCheck.hasKey && !pickedProvider) {
+      if (
+        !apiKeyCheck.hasKey &&
+        !pickedProvider &&
+        !process.env.VELLUM_DESKTOP_APP
+      ) {
         reporter.warn(
           "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
         );

package/src/lib/live-voice/client.ts

@@ -53,6 +53,13 @@ type EventName = keyof LiveVoiceClientEvents;
 export interface CliLiveVoiceClientOptions {
   readonly url: string;
   readonly token: string;
+  /**
+   * Where the credential goes. `header` is the gateway's `Authorization:
+   * Bearer` (the local and self-hosted path); `query` means the URL already
+   * carries the token velay reads, and no header is sent. Defaults to `header`
+   * so existing callers keep the gateway behaviour.
+   */
+  readonly tokenTransport?: "header" | "query";
   readonly conversationId?: string;
   /** Override the socket factory (tests). */
   readonly webSocketFactory?: (url: string, token: string) => WebSocket;
@@ -118,7 +125,11 @@ export class CliLiveVoiceClient {
     try {
       ws = this.options.webSocketFactory
         ? this.options.webSocketFactory(this.options.url, this.options.token)
-        : openAuthenticatedSocket(this.options.url, this.options.token);
+        : openAuthenticatedSocket(
+            this.options.url,
+            this.options.token,
+            this.options.tokenTransport ?? "header",
+          );
     } catch (err) {
       this.fail(
         err instanceof Error
@@ -340,7 +351,17 @@ export class CliLiveVoiceClient {
  * process listings, shell history, and gateway access logs, and this token is
  * the bound guardian's.
  */
-function openAuthenticatedSocket(url: string, token: string): WebSocket {
+function openAuthenticatedSocket(
+  url: string,
+  token: string,
+  transport: "header" | "query",
+): WebSocket {
+  // velay reads the credential from the query string and no headers at all,
+  // and the URL it was given already carries it. Sending a bearer header there
+  // would authenticate nothing and put a single-use token in a second place.
+  if (transport === "query") {
+    return new WebSocket(url) as WebSocket;
+  }
   return new WebSocket(url, {
     headers: { Authorization: `Bearer ${token}` },
   } as unknown as string[]) as WebSocket;