@vellumai/cli 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/commands/message.ts

@@ -6,6 +6,8 @@
  * subscribe to SSE events (use `vellum events` for that).
  */
 
+import { readFileSync } from "node:fs";
+
 import { extractFlag } from "../lib/arg-utils.js";
 import { AssistantClient } from "../lib/assistant-client.js";
 
@@ -14,57 +16,145 @@ function printUsage(): void {
 
 USAGE:
     vellum message [assistant] <message>
+    vellum message [assistant] --file <path>
 
 ARGUMENTS:
     [assistant]    Instance name (default: active assistant)
-    <message>      Message content to send
+    <message>      Message content to send (omit when using --file)
 
 OPTIONS:
+    --file <path>             Read message content from a file ("-" reads stdin)
     --conversation-key <key>  Conversation key (default: stable key per channel/interface)
     --json                    Output raw JSON response
 
 EXAMPLES:
     vellum message "hello"
     vellum message my-assistant "ping"
+    vellum message --file prompt.txt
+    vellum message my-assistant --file prompt.txt
+    cat prompt.txt | vellum message --file -
     vellum message --conversation-key my-thread "hello"
     vellum message --json "hello"
 `);
 }
 
-export async function message(): Promise<void> {
-  const rawArgs = process.argv.slice(3);
+interface ParsedMessageArgs {
+  assistantId?: string;
+  conversationKey?: string;
+  jsonOutput: boolean;
+  /** Path to read message content from, or undefined for an inline message. */
+  filePath?: string;
+  /** Inline message content, present only when --file was not used. */
+  inlineMessage?: string;
+}
 
-  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-    printUsage();
-    return;
-  }
+type ParseResult =
+  | { ok: true; value: ParsedMessageArgs }
+  | { ok: false; error: string };
 
+/**
+ * Parse `vellum message` arguments. Pure: does no I/O and never exits, so the
+ * positional/flag rules can be unit-tested. File reading and validation of the
+ * resolved content happen in {@link message}.
+ */
+export function parseMessageArgs(rawArgs: string[]): ParseResult {
   const jsonOutput = rawArgs.includes("--json");
   let args = rawArgs.filter((a) => a !== "--json");
 
-  const [conversationKey, filteredArgs] = extractFlag(
+  const [conversationKey, afterConversationKey] = extractFlag(
     args,
     "--conversation-key",
   );
-  args = filteredArgs;
+  args = afterConversationKey;
+
+  const fileFlagPresent = args.includes("--file");
+  const [filePath, afterFile] = extractFlag(args, "--file");
+  args = afterFile;
+
+  // `extractFlag` strips a trailing value-less `--file`, which would otherwise
+  // make the next positional masquerade as the message content. Reject it.
+  if (fileFlagPresent && filePath === undefined) {
+    return { ok: false, error: "--file requires a path argument." };
+  }
 
-  let assistantId: string | undefined;
-  let messageContent: string | undefined;
+  if (filePath !== undefined) {
+    // vellum message [assistant] --file <path>
+    // The message content comes from the file, so any remaining positional
+    // arg is the assistant target.
+    if (args.length >= 2) {
+      return {
+        ok: false,
+        error: "--file cannot be combined with an inline message argument.",
+      };
+    }
+    return {
+      ok: true,
+      value: { assistantId: args[0], conversationKey, jsonOutput, filePath },
+    };
+  }
 
   if (args.length >= 2) {
     // vellum message <assistant> <message>
-    assistantId = args[0];
-    messageContent = args[1];
-  } else if (args.length === 1) {
+    return {
+      ok: true,
+      value: {
+        assistantId: args[0],
+        conversationKey,
+        jsonOutput,
+        inlineMessage: args[1],
+      },
+    };
+  }
+  if (args.length === 1) {
     // vellum message <message>  (uses active/latest assistant)
-    messageContent = args[0];
+    return {
+      ok: true,
+      value: { conversationKey, jsonOutput, inlineMessage: args[0] },
+    };
   }
 
-  if (!messageContent) {
-    console.error("Error: message content is required.");
-    console.error("");
+  return { ok: false, error: "message content is required." };
+}
+
+function exitWithUsage(error: string): never {
+  console.error(`Error: ${error}`);
+  console.error("");
+  printUsage();
+  process.exit(1);
+}
+
+export async function message(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
     printUsage();
-    process.exit(1);
+    return;
+  }
+
+  const parsed = parseMessageArgs(rawArgs);
+  if (!parsed.ok) {
+    exitWithUsage(parsed.error);
+  }
+
+  const { assistantId, conversationKey, jsonOutput, filePath, inlineMessage } =
+    parsed.value;
+
+  let messageContent: string;
+  if (filePath !== undefined) {
+    try {
+      messageContent = readFileSync(filePath === "-" ? 0 : filePath, "utf-8");
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Error: could not read message file "${filePath}": ${reason}`,
+      );
+      process.exit(1);
+    }
+    if (messageContent.length === 0) {
+      exitWithUsage(`message file "${filePath}" is empty.`);
+    }
+  } else {
+    messageContent = inlineMessage ?? "";
   }
 
   const client = new AssistantClient({ assistantId });

package/src/commands/teleport.ts

@@ -891,6 +891,7 @@ export async function resolveOrHatchTarget(
       false,
       false,
       {},
+      {},
       {
         setupProviderCredentials: false,
       },
@@ -915,6 +916,7 @@ export async function resolveOrHatchTarget(
       targetName ?? null,
       false,
       {},
+      {},
       {
         setupProviderCredentials: false,
       },

package/src/components/DefaultMainScreen.tsx

@@ -12,7 +12,12 @@ import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { lookupAssistantByIdentifier } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
-import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
+import {
+  guardianTokenDueForRenewal,
+  loadGuardianToken,
+  refreshGuardianToken,
+} from "../lib/guardian-token";
+import { trustedRefreshUrl } from "../lib/runtime-url";
 import { appendHistory, loadHistory } from "../lib/input-history";
 import { tuiLog } from "../lib/tui-log";
 import { segmentsToPlainText } from "../lib/segments-to-plain-text";
@@ -193,6 +198,16 @@ function friendlyErrorMessage(status: number, body: string): string {
  * and access-only tokens. Because the TUI threads one shared `auth` object by
  * reference, mutating it here propagates to every later request and the SSE
  * reconnect — no callback threading needed.
+ *
+ * SECURITY: the refresh is bound to the paired entry's persisted runtime URL.
+ * `vellum client` lets `--url`/`-u` override the runtime URL while still using
+ * the selected paired entry's stored guardian token, so a victim pointed at an
+ * attacker-controlled (or poisoned/redirected) URL that returns 401 must NOT
+ * cause us to POST the long-lived refreshToken + deviceId to that origin. We
+ * therefore (a) refuse to refresh unless `baseUrl` normalizes to one of the
+ * entry's persisted URLs, and (b) send the refresh to the persisted URL rather
+ * than the caller-supplied `baseUrl` — defense in depth if the gate is ever
+ * bypassed.
  */
 export async function maybeRefreshAuthHeaders(
   baseUrl: string,
@@ -210,11 +225,21 @@ export async function maybeRefreshAuthHeaders(
     return false;
   }
 
+  // Bind the refresh origin to the persisted paired entry: refuse (and never
+  // leak credentials) if `baseUrl` was overridden via --url or poisoned to an
+  // origin that isn't one of the entry's persisted URLs. `refreshUrl` is the
+  // trusted persisted URL we actually send to.
+  const refreshUrl = trustedRefreshUrl(lookup.entry, baseUrl);
+  if (!refreshUrl) return false;
+
   const stored = loadGuardianToken(assistantId);
   if (!stored || stored.accessToken !== bearer || !stored.refreshToken) {
     return false;
   }
-  const refreshed = await refreshGuardianToken(baseUrl, assistantId);
+  // Only refresh once the token is actually due for renewal, so a forged 401
+  // on a still-valid token can't coax out the long-lived refresh credential.
+  if (!guardianTokenDueForRenewal(stored)) return false;
+  const refreshed = await refreshGuardianToken(refreshUrl, assistantId);
   if (!refreshed?.accessToken) return false;
   auth["Authorization"] = `Bearer ${refreshed.accessToken}`;
   return true;

package/src/lib/__tests__/docker.test.ts

@@ -1,7 +1,11 @@
 import { afterEach, beforeEach, describe, test, expect } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
 import {
   ASSISTANT_INTERNAL_PORT,
   AVATAR_DEVICE_ENV_VAR,
+  collectWatchTargets,
   dockerResourceNames,
   resolveAvatarDevicePath,
   resolveDockerHatchMode,
@@ -277,3 +281,98 @@ describe("resolveDockerHatchMode", () => {
     ).toEqual({ build: false, watcher: false, fellBackToPull: true });
   });
 });
+
+describe("collectWatchTargets", () => {
+  let repoRoot: string;
+
+  beforeEach(() => {
+    repoRoot = mkdtempSync(join(tmpdir(), "vellum-watch-"));
+  });
+
+  afterEach(() => {
+    rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  function scaffold(
+    relDir: string,
+    { src = true, pkg = true, dockerfile = false } = {},
+  ): void {
+    mkdirSync(join(repoRoot, relDir), { recursive: true });
+    if (src) mkdirSync(join(repoRoot, relDir, "src"), { recursive: true });
+    if (pkg) writeFileSync(join(repoRoot, relDir, "package.json"), "{}");
+    if (dockerfile) writeFileSync(join(repoRoot, relDir, "Dockerfile"), "");
+  }
+
+  test("scopes watch targets to src/, package.json, and the Dockerfile", () => {
+    // GIVEN the three services (each with a Dockerfile) plus a couple of
+    // shared packages (libraries, no Dockerfile)
+    scaffold("assistant", { dockerfile: true });
+    scaffold("credential-executor", { dockerfile: true });
+    scaffold("gateway", { dockerfile: true });
+    scaffold("packages/service-contracts");
+    scaffold("packages/local-mode");
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN only the src/ directories are watched recursively
+    expect(dirs.sort()).toEqual(
+      [
+        join(repoRoot, "assistant", "src"),
+        join(repoRoot, "credential-executor", "src"),
+        join(repoRoot, "gateway", "src"),
+        join(repoRoot, "packages", "local-mode", "src"),
+        join(repoRoot, "packages", "service-contracts", "src"),
+      ].sort(),
+    );
+
+    // AND the package.json manifests and service Dockerfiles are watched as
+    // individual files (packages have no Dockerfile, so none is emitted)
+    expect(files.sort()).toEqual(
+      [
+        join(repoRoot, "assistant", "package.json"),
+        join(repoRoot, "assistant", "Dockerfile"),
+        join(repoRoot, "credential-executor", "package.json"),
+        join(repoRoot, "credential-executor", "Dockerfile"),
+        join(repoRoot, "gateway", "package.json"),
+        join(repoRoot, "gateway", "Dockerfile"),
+        join(repoRoot, "packages", "local-mode", "package.json"),
+        join(repoRoot, "packages", "service-contracts", "package.json"),
+      ].sort(),
+    );
+  });
+
+  test("never watches .claude/ command symlinks that crash the watcher", () => {
+    // GIVEN an assistant service whose .claude/commands holds a dangling
+    // symlink (as it does in a fresh checkout)
+    scaffold("assistant");
+    mkdirSync(join(repoRoot, "assistant", ".claude", "commands"), {
+      recursive: true,
+    });
+    symlinkSync(
+      join(repoRoot, "does-not-exist", "do.md"),
+      join(repoRoot, "assistant", ".claude", "commands", "do.md"),
+    );
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN no watched path reaches into the .claude/ tree
+    const all = [...dirs, ...files];
+    expect(all.some((p) => p.includes(".claude"))).toBe(false);
+    expect(dirs).toContain(join(repoRoot, "assistant", "src"));
+  });
+
+  test("skips roots missing a src/ directory or package.json", () => {
+    // GIVEN a service with only a manifest and a package with only a src/ dir
+    scaffold("gateway", { src: false, pkg: true });
+    scaffold("packages/contracts-only", { src: true, pkg: false });
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN absent paths are not emitted
+    expect(dirs).toEqual([join(repoRoot, "packages", "contracts-only", "src")]);
+    expect(files).toEqual([join(repoRoot, "gateway", "package.json")]);
+  });
+});

package/src/lib/assistant-client.ts

@@ -14,7 +14,11 @@
 
 import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
-import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+  guardianTokenDueForRenewal,
+} from "./guardian-token.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -219,21 +223,35 @@ export class AssistantClient {
 
     const response = await doFetch();
 
-    // Reactive auto-refresh: a paired/local guardian access token that has
-    // expired comes back 401. Refresh it once via the stored refresh credential
-    // and retry. Self-gating — refreshGuardianToken returns null unless a usable
-    // refresh token is stored, so ephemeral (`--token`) and access-only sessions
-    // just see the original 401. The platform session-auth path is never
-    // refreshed here (its token is managed by the Vellum platform).
+    // 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) {
-      const refreshed = await refreshGuardianToken(
-        this.runtimeUrl,
-        this._assistantId,
-      );
-      if (refreshed?.accessToken) {
-        this.token = refreshed.accessToken;
+      const stored = loadGuardianToken(this._assistantId);
+
+      // Another process may have already rotated and persisted a fresh access
+      // token (e.g. a concurrent `vellum events`). Adopt it and retry — this
+      // sends no refresh credential, just picks up the newer local token.
+      if (stored?.accessToken && stored.accessToken !== this.token) {
+        this.token = stored.accessToken;
         return doFetch();
       }
+
+      // Otherwise only disclose the long-lived refresh token when our access
+      // token is actually due for renewal. A 401 on a still-valid token (e.g. a
+      // forged 401 from an impostor endpoint trying to coax out the refresh
+      // credential) is surfaced as-is, not refreshed.
+      if (stored?.refreshToken && guardianTokenDueForRenewal(stored)) {
+        const refreshed = await refreshGuardianToken(
+          this.runtimeUrl,
+          this._assistantId,
+        );
+        if (refreshed?.accessToken) {
+          this.token = refreshed.accessToken;
+          return doFetch();
+        }
+      }
     }
 
     return response;

package/src/lib/docker.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   watch as fsWatch,
 } from "fs";
 import { arch, platform } from "os";
@@ -661,6 +662,7 @@ export async function startContainers(
     bootstrapSecret?: string;
     cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
+    extraGatewayEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
     instanceName: string;
@@ -788,6 +790,56 @@ export async function captureImageRefs(
   return hasAll ? (refs as Record<ServiceName, string>) : null;
 }
 
+/**
+ * Build the set of paths the hot-reload watcher should observe, scoped to
+ * each service's `src/` tree, `package.json` manifest, and `Dockerfile`.
+ *
+ * We deliberately avoid recursively watching whole service directories.
+ * Those contain `.claude/` command symlinks — which dangle in a fresh
+ * checkout because they point at the separately-cloned `claude-skills`
+ * repo — as well as `node_modules`. `fs.watch(dir, { recursive: true })`
+ * traverses those entries and emits an unhandled `error` event on a broken
+ * symlink, which crashes the CLI process. Source code only ever lives under
+ * `src/`, so watching that tree plus the two manifests that drive the image
+ * build (`package.json` and `Dockerfile`) preserves hot-reload without
+ * walking into symlinked or generated trees. The `Dockerfile` is watched as
+ * an individual file for the same reason — editing build steps should
+ * trigger a rebuild, but the file sits next to the symlinked trees we avoid.
+ *
+ * Returning a plain record keeps this trivially unit-testable — see
+ * `__tests__/docker.test.ts`.
+ */
+export function collectWatchTargets(repoRoot: string): {
+  dirs: string[];
+  files: string[];
+} {
+  const packagesDir = join(repoRoot, "packages");
+  const packageRoots = existsSync(packagesDir)
+    ? readdirSync(packagesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(packagesDir, entry.name))
+    : [];
+
+  const serviceRoots = [
+    join(repoRoot, "assistant"),
+    join(repoRoot, "credential-executor"),
+    join(repoRoot, "gateway"),
+    ...packageRoots,
+  ];
+
+  const dirs: string[] = [];
+  const files: string[] = [];
+  for (const root of serviceRoots) {
+    const srcDir = join(root, "src");
+    if (existsSync(srcDir)) dirs.push(srcDir);
+    for (const name of ["package.json", "Dockerfile"]) {
+      const file = join(root, name);
+      if (existsSync(file)) files.push(file);
+    }
+  }
+  return { dirs, files };
+}
+
 /**
  * Determine which services are affected by a changed file path relative
  * to the repository root.
@@ -821,9 +873,10 @@ function affectedServices(
 }
 
 /**
- * Watch for file changes in the assistant, gateway, credential-executor,
- * and packages directories. When changes are detected, rebuild the affected
- * images and restart their containers.
+ * Watch for source changes across the assistant, gateway, credential-executor,
+ * and packages services — scoped to each service's `src/` tree, `package.json`,
+ * and `Dockerfile` (see `collectWatchTargets`). When changes are detected,
+ * rebuild the affected images and restart their containers.
  */
 function startFileWatcher(opts: {
   signingKey?: string;
@@ -837,12 +890,7 @@ function startFileWatcher(opts: {
 }): () => void {
   const { gatewayPort, imageTags, instanceName, repoRoot, res } = opts;
 
-  const watchDirs = [
-    join(repoRoot, "assistant"),
-    join(repoRoot, "credential-executor"),
-    join(repoRoot, "gateway"),
-    join(repoRoot, "packages"),
-  ];
+  const { dirs: watchDirs, files: watchFiles } = collectWatchTargets(repoRoot);
 
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let pendingServices = new Set<ServiceName>();
@@ -919,37 +967,53 @@ function startFileWatcher(opts: {
 
   const watchers: ReturnType<typeof fsWatch>[] = [];
 
+  function onChange(fullPath: string): void {
+    const services = affectedServices(fullPath, repoRoot);
+    if (services.size === 0) return;
+
+    for (const s of services) {
+      pendingServices.add(s);
+    }
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      rebuildAndRestart();
+    }, 500);
+  }
+
   for (const dir of watchDirs) {
-    if (!existsSync(dir)) continue;
     const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
       if (!filename) return;
-      if (
-        filename.includes("node_modules") ||
-        filename.includes(".env") ||
-        filename.startsWith(".")
-      ) {
+      if (filename.includes("node_modules") || filename.includes(".env")) {
         return;
       }
+      onChange(join(dir, filename));
+    });
+    // fs.watch surfaces transient errors (e.g. an unreadable entry) as an
+    // `error` event, which would otherwise crash the process. Log and keep
+    // the remaining watchers running.
+    watcher.on("error", (err) => {
+      console.error(
+        `⚠️  File watcher error for ${dir}: ${err instanceof Error ? err.message : err}`,
+      );
+    });
+    watchers.push(watcher);
+  }
 
-      const fullPath = join(dir, filename);
-      const services = affectedServices(fullPath, repoRoot);
-      if (services.size === 0) return;
-
-      for (const s of services) {
-        pendingServices.add(s);
-      }
-
-      if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        debounceTimer = null;
-        rebuildAndRestart();
-      }, 500);
+  for (const file of watchFiles) {
+    const watcher = fsWatch(file, () => onChange(file));
+    watcher.on("error", (err) => {
+      console.error(
+        `⚠️  File watcher error for ${file}: ${err instanceof Error ? err.message : err}`,
+      );
     });
     watchers.push(watcher);
   }
 
   console.log("👀 Watching for file changes in:");
-  console.log("   assistant/, gateway/, credential-executor/, packages/");
+  console.log("   <service>/src, <service>/package.json, <service>/Dockerfile");
+  console.log("   for assistant/, gateway/, credential-executor/, packages/*");
   console.log("");
 
   return () => {
@@ -979,6 +1043,7 @@ export async function hatchDocker(
   name: string | null,
   watch: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchDockerOptions = {},
 ): Promise<void> {
   resetLogFile("hatch.log");
@@ -1258,12 +1323,15 @@ export async function hatchDocker(
       : ownSecret;
 
     emitProgress(4, 6, "Starting containers...");
+    const extraGatewayEnv =
+      Object.keys(flagEnvVars).length > 0 ? flagEnvVars : undefined;
     await startContainers(
       {
         signingKey,
         bootstrapSecret,
         cesServiceToken,
         extraAssistantEnv,
+        extraGatewayEnv,
         gatewayPort,
         imageTags,
         instanceName,