@vellumai/cli 0.8.1 → 0.8.3

package/README.md

@@ -54,27 +54,25 @@ vellum hatch [species] [options]
 
 #### Options
 
-| Option              | Description                                                                                    |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `-d`                | Detached mode. Start the instance in the background without watching startup progress.         |
-| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                 |
-| `--remote <target>` | Where to provision the instance. One of: `local`, `gcp`, `aws`, `custom`. Defaults to `local`. |
+| Option              | Description                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `-d`                | Detached mode. Start the instance in the background without watching startup progress.                             |
+| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                                     |
+| `--remote <target>` | Where to provision the instance. One of: `local`, `docker`, `vellum`, `gcp`, `aws`, `custom`. Defaults to `local`. |
 
 #### Remote Targets
 
 - **`local`** -- Starts the local assistant and local gateway. Gateway source resolution order is: repo source tree, then installed `@vellumai/vellum-gateway` package.
-- **`gcp`** -- Creates a GCP Compute Engine VM (`e2-standard-4`: 4 vCPUs, 16 GB) with a startup script that bootstraps the assistant. Requires `gcloud` authentication and `GCP_PROJECT` / `GCP_DEFAULT_ZONE` environment variables.
-- **`aws`** -- Provisions an AWS instance.
-- **`custom`** -- Provisions on an arbitrary SSH host. Set `VELLUM_CUSTOM_HOST` (e.g. `user@hostname`) to specify the target.
+- **`docker`** -- Starts the assistant, gateway, and credential service in Docker containers.
+- **`vellum`** -- Hatches an assistant on the Vellum platform.
+- **`gcp`** and **`aws`** -- Recognized but not supported as provisioning targets yet. The CLI exits before creating cloud resources. To self-host on AWS/GCP, SSH into the VM and run `vellum hatch` or `vellum hatch --remote docker` there.
+- **`custom`** -- Recognized but not yet implemented.
 
 #### Environment Variables
 
-| Variable             | Required For | Description                                                |
-| -------------------- | ------------ | ---------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`  | All          | Anthropic API key passed to the assistant runtime.         |
-| `GCP_PROJECT`        | `gcp`        | GCP project ID. Falls back to the active `gcloud` project. |
-| `GCP_DEFAULT_ZONE`   | `gcp`        | GCP zone for the compute instance.                         |
-| `VELLUM_CUSTOM_HOST` | `custom`     | SSH host in `user@hostname` format.                        |
+| Variable            | Required For | Description                                                                |
+| ------------------- | ------------ | -------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY` | Optional     | Used during setup when no Anthropic API key is already stored or prompted. |
 
 #### Examples
 
@@ -82,20 +80,14 @@ vellum hatch [species] [options]
 # Hatch a local assistant (default)
 vellum hatch
 
-# Hatch a vellum assistant on GCP
-vellum hatch vellum --remote gcp
-
-# Hatch an openclaw assistant on GCP in detached mode
-vellum hatch openclaw --remote gcp -d
+# Hatch a Docker assistant
+vellum hatch --remote docker
 
 # Hatch with a specific instance name
-vellum hatch --name my-assistant --remote gcp
-
-# Hatch on a custom SSH host
-VELLUM_CUSTOM_HOST=user@10.0.0.1 vellum hatch --remote custom
+vellum hatch --name my-assistant --remote docker
 ```
 
-When hatching on GCP in interactive mode (without `-d`), the CLI displays an animated progress TUI that polls the instance's startup script output in real time. Press `Ctrl+C` to detach -- the instance will continue running in the background.
+AWS and GCP hatch targets are recognized so users receive an explicit unsupported-target error instead of an unknown-option error. They currently exit without creating cloud resources; self-hosting on an AWS/GCP VM still works by running `vellum hatch` from inside that machine.
 
 ### `terminal`
 
@@ -111,18 +103,18 @@ Only available for managed assistants (those running in a Vellum Cloud container
 
 #### Subcommands
 
-| Subcommand         | Description                                                              |
-| ------------------ | ------------------------------------------------------------------------ |
-| _(none)_           | Open an interactive shell session inside the container.                  |
-| `attach <session>` | Attach to an existing `tmux` session by name inside the container.       |
-| `list`             | List the `tmux` sessions currently running inside the container.         |
+| Subcommand         | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| _(none)_           | Open an interactive shell session inside the container.            |
+| `attach <session>` | Attach to an existing `tmux` session by name inside the container. |
+| `list`             | List the `tmux` sessions currently running inside the container.   |
 
 #### Options
 
-| Option               | Description                                                                                  |
-| -------------------- | -------------------------------------------------------------------------------------------- |
+| Option               | Description                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
 | `[name]`             | Positional. Name of the assistant to target. Defaults to the active assistant set via `vellum use`. |
-| `--assistant <name>` | Explicit form of the assistant name. Equivalent to the positional argument.                  |
+| `--assistant <name>` | Explicit form of the assistant name. Equivalent to the positional argument.                         |
 
 If no assistant is named and no active assistant is set, the CLI uses the only managed assistant in the lockfile -- or errors out if there's more than one. Use `vellum ps` to see your assistants and `vellum use <name>` to set the active one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/backup.test.ts

@@ -81,12 +81,20 @@ const localRuntimePollJobStatusMock = spyOn(
 
 // Mode 1 (runtime-direct local backup) uses guardian tokens. Don't exercise
 // it here, but the spies need to exist so the module under test can import
-// them without surprises.
-spyOn(guardianToken, "loadGuardianToken").mockReturnValue({
+// them without surprises. Saved to variables so afterAll can restore them —
+// otherwise the spied loadGuardianToken leaks into guardian-token.test.ts and
+// setup.test.ts when they run later in the same `bun test` invocation.
+const loadGuardianTokenSpy = spyOn(
+  guardianToken,
+  "loadGuardianToken",
+).mockReturnValue({
   accessToken: "local-token",
   accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
 } as unknown as ReturnType<typeof guardianToken.loadGuardianToken>);
-spyOn(guardianToken, "leaseGuardianToken").mockResolvedValue({
+const leaseGuardianTokenSpy = spyOn(
+  guardianToken,
+  "leaseGuardianToken",
+).mockResolvedValue({
   accessToken: "leased-token",
   accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
 } as unknown as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>);
@@ -177,6 +185,8 @@ afterAll(() => {
   getBackupsDirMock.mockRestore();
   mkdirSyncMock.mockRestore();
   writeFileSyncMock.mockRestore();
+  loadGuardianTokenSpy.mockRestore();
+  leaseGuardianTokenSpy.mockRestore();
   rmSync(testDir, { recursive: true, force: true });
 });
 

package/src/__tests__/config-utils.test.ts

@@ -1,7 +1,11 @@
 import { readFileSync, rmSync } from "fs";
 import { describe, expect, test } from "bun:test";
 
-import { buildNestedConfig, writeInitialConfig } from "../lib/config-utils.js";
+import {
+  buildHatchConfigValues,
+  buildNestedConfig,
+  writeInitialConfig,
+} from "../lib/config-utils.js";
 
 function readInitialConfig(
   configValues: Record<string, string>,
@@ -32,6 +36,32 @@ describe("config-utils", () => {
     });
   });
 
+  test("buildHatchConfigValues adds the default hatch provider when no config exists", () => {
+    expect(buildHatchConfigValues({}, "anthropic")).toEqual({
+      "llm.default.provider": "anthropic",
+    });
+  });
+
+  test("buildHatchConfigValues preserves explicit provider config", () => {
+    expect(
+      buildHatchConfigValues(
+        {
+          "llm.default.provider": "openai",
+          "llm.default.model": "gpt-5.4",
+        },
+        "anthropic",
+      ),
+    ).toEqual({
+      "llm.default.provider": "openai",
+      "llm.default.model": "gpt-5.4",
+    });
+  });
+
+  test("buildHatchConfigValues skips internal hatches without provider setup", () => {
+    expect(buildHatchConfigValues({}, undefined)).toEqual({});
+    expect(buildHatchConfigValues({}, null)).toEqual({});
+  });
+
   test("writeInitialConfig does not add a mainAgent callSite for Anthropic defaults", () => {
     expect(
       readInitialConfig({

package/src/__tests__/hatch-provider-secrets.test.ts

@@ -0,0 +1,284 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  configureHatchProviderApiKey,
+  resolveHatchProvider,
+  type ProviderSecretFetch,
+} from "../lib/provider-secrets.js";
+
+interface RecordedFetchCall {
+  url: string;
+  init?: RequestInit;
+  body: unknown;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function makeFetch(responses: Response[]): {
+  calls: RecordedFetchCall[];
+  fetchImpl: ProviderSecretFetch;
+} {
+  const calls: RecordedFetchCall[] = [];
+  const fetchImpl: ProviderSecretFetch = async (input, init) => {
+    calls.push({
+      url: String(input),
+      init,
+      body: typeof init?.body === "string" ? JSON.parse(init.body) : init?.body,
+    });
+    const response = responses.shift();
+    if (!response) {
+      throw new Error("Unexpected fetch call.");
+    }
+    return response;
+  };
+
+  return { calls, fetchImpl };
+}
+
+describe("hatch provider secrets", () => {
+  test("defaults hatch provider setup to Anthropic", () => {
+    expect(resolveHatchProvider({})).toBe("anthropic");
+  });
+
+  test("uses llm.default.provider override for hatch provider setup", () => {
+    expect(resolveHatchProvider({ "llm.default.provider": "openai" })).toBe(
+      "openai",
+    );
+  });
+
+  test("uses active profile provider for hatch provider setup", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("openai");
+  });
+
+  test("infers active profile provider from model for hatch provider setup", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.model": "gpt-5.4",
+      }),
+    ).toBe("openai");
+  });
+
+  test("active profile provider wins over main agent call-site provider", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("openai");
+  });
+
+  test("uses default provider before static main agent call-site provider", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.default.provider": "anthropic",
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("anthropic");
+  });
+
+  test("uses default provider before static main agent call-site profile", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.default.provider": "anthropic",
+        "llm.callSites.mainAgent.profile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("anthropic");
+  });
+
+  test("uses main agent call-site provider when no hatch default exists", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("gemini");
+  });
+
+  test("uses main agent call-site profile when no hatch default exists", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.callSites.mainAgent.profile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("openai");
+  });
+
+  test("infers default provider from model before falling back to Anthropic", () => {
+    expect(
+      resolveHatchProvider({ "llm.default.model": "gemini-2.5-flash" }),
+    ).toBe("gemini");
+  });
+
+  test("skips hatch provider setup for ollama", () => {
+    expect(
+      resolveHatchProvider({ "llm.default.provider": "ollama" }),
+    ).toBeNull();
+  });
+
+  test("skips hatch provider setup for active Ollama profile", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "local",
+        "llm.profiles.local.model": "llama3.2",
+      }),
+    ).toBeNull();
+  });
+
+  test("rejects unsupported hatch providers before hatch starts", () => {
+    expect(() =>
+      resolveHatchProvider({ "llm.default.provider": "custom" }),
+    ).toThrow("supported API-key setup flow");
+  });
+
+  test("configures default Anthropic credentials from the environment", async () => {
+    const { calls, fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse({ success: true }),
+    ]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({}),
+      bearerToken: "guardian-token",
+      env: { ANTHROPIC_API_KEY: "test-anthropic-key" },
+      fetchImpl,
+      log: (message) => logs.push(message),
+    });
+
+    expect(calls).toHaveLength(2);
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "anthropic",
+      reveal: false,
+    });
+    expect(calls[0].init?.headers).toMatchObject({
+      Authorization: "Bearer guardian-token",
+    });
+    expect(calls[1].body).toEqual({
+      type: "api_key",
+      name: "anthropic",
+      value: "test-anthropic-key",
+    });
+    expect(logs.join("\n")).toContain(
+      "Configured Anthropic credentials from ANTHROPIC_API_KEY.",
+    );
+    expect(logs.join("\n")).not.toContain("test-anthropic-key");
+  });
+
+  test("uses OpenAI override and skips prompt when credentials already exist", async () => {
+    const { calls, fetchImpl } = makeFetch([jsonResponse({ found: true })]);
+    const logs: string[] = [];
+    let prompted = false;
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({ "llm.default.provider": "openai" }),
+      bearerToken: "guardian-token",
+      env: {},
+      fetchImpl,
+      prompt: async () => {
+        prompted = true;
+        return "unused";
+      },
+      log: (message) => logs.push(message),
+    });
+
+    expect(prompted).toBe(false);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      reveal: false,
+    });
+    expect(logs.join("\n")).toContain(
+      "Provider credentials already configured for OpenAI.",
+    );
+  });
+
+  test("uses active profile provider when selecting environment credential", async () => {
+    const { calls, fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse({ success: true }),
+    ]);
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+      bearerToken: "guardian-token",
+      env: { OPENAI_API_KEY: "test-openai-key" },
+      fetchImpl,
+      log: () => {},
+    });
+
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      reveal: false,
+    });
+    expect(calls[1].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      value: "test-openai-key",
+    });
+  });
+
+  test("keeps hatch recoverable when provider credentials are missing in a non-interactive shell", async () => {
+    const { fetchImpl } = makeFetch([jsonResponse({ found: false })]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: "anthropic",
+      env: {},
+      fetchImpl,
+      stdinIsTTY: false,
+      log: (message) => logs.push(message),
+    });
+
+    const output = logs.join("\n");
+    expect(output).toContain("Provider credential setup skipped");
+    expect(output).toContain("Missing ANTHROPIC_API_KEY");
+    expect(output).toContain("vellum setup --provider anthropic");
+  });
+
+  test("surfaces gateway validation failures without throwing or logging the key", async () => {
+    const { fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse(
+        { error: { message: "API key is invalid or expired." } },
+        400,
+      ),
+    ]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: "anthropic",
+      env: { ANTHROPIC_API_KEY: "test-anthropic-key" },
+      fetchImpl,
+      log: (message) => logs.push(message),
+    });
+
+    const output = logs.join("\n");
+    expect(output).toContain("Provider credential setup failed");
+    expect(output).toContain("API key is invalid or expired.");
+    expect(output).toContain("vellum setup --provider anthropic");
+    expect(output).not.toContain("test-anthropic-key");
+  });
+});

package/src/__tests__/input-history.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { getInputHistoryPath } from "../lib/environments/paths.js";
+import { appendHistory, loadHistory } from "../lib/input-history.js";
+
+describe("input-history XDG paths", () => {
+  let tempDir: string;
+  let savedState: string | undefined;
+
+  beforeEach(() => {
+    savedState = process.env.XDG_STATE_HOME;
+    tempDir = mkdtempSync(join(tmpdir(), "cli-input-history-test-"));
+    process.env.XDG_STATE_HOME = join(tempDir, ".local", "state");
+  });
+
+  afterEach(() => {
+    if (savedState === undefined) {
+      delete process.env.XDG_STATE_HOME;
+    } else {
+      process.env.XDG_STATE_HOME = savedState;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("appendHistory writes to $XDG_STATE_HOME/vellum/input-history", () => {
+    appendHistory("hello world");
+
+    const canonical = getInputHistoryPath();
+    expect(canonical).toBe(
+      join(tempDir, ".local", "state", "vellum", "input-history"),
+    );
+    expect(existsSync(canonical)).toBe(true);
+    expect(readFileSync(canonical, "utf-8")).toBe("hello world\n");
+  });
+
+  test("appendHistory does NOT touch ~/.vellum/", () => {
+    // Crucially: the CLI must not create or write to ~/.vellum/ per the
+    // "No `.vellum/` directory access" boundary in cli/AGENTS.md. We snapshot
+    // the legacy path's existence before the call (some test machines already
+    // have a ~/.vellum/ for unrelated daemon state) and assert the file at
+    // that path is unchanged afterwards.
+    const legacyPath = join(homedir(), ".vellum", "input-history");
+    const existedBefore = existsSync(legacyPath);
+    const contentBefore: string = existedBefore
+      ? readFileSync(legacyPath, "utf-8")
+      : "";
+
+    appendHistory("hello");
+
+    expect(existsSync(legacyPath)).toBe(existedBefore);
+    if (existedBefore) {
+      expect(readFileSync(legacyPath, "utf-8")).toBe(contentBefore);
+    }
+  });
+
+  test("XDG_STATE_HOME default is ~/.local/state when unset", () => {
+    delete process.env.XDG_STATE_HOME;
+
+    // os.homedir() is cached at process start by Bun and ignores
+    // process.env.HOME mutations, so compute the expected path from the same
+    // source the production helper uses.
+    expect(getInputHistoryPath()).toBe(
+      join(homedir(), ".local", "state", "vellum", "input-history"),
+    );
+  });
+
+  test("appendHistory skips empty and slash-command entries", () => {
+    appendHistory("");
+    appendHistory("   ");
+    appendHistory("/help");
+    appendHistory("real entry");
+
+    expect(loadHistory()).toEqual(["real entry"]);
+  });
+
+  test("appendHistory deduplicates by moving to most recent", () => {
+    appendHistory("a");
+    appendHistory("b");
+    appendHistory("a");
+
+    expect(loadHistory()).toEqual(["b", "a"]);
+  });
+
+  test("appendHistory caps history at MAX_ENTRIES (1000)", () => {
+    for (let i = 0; i < 1100; i++) {
+      appendHistory(`entry-${i}`);
+    }
+
+    const history = loadHistory();
+    expect(history.length).toBe(1000);
+    expect(history[0]).toBe("entry-100");
+    expect(history[999]).toBe("entry-1099");
+  });
+});

package/src/__tests__/preload.ts

@@ -10,7 +10,7 @@
 import { mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterAll } from "bun:test";
+import { afterAll, mock } from "bun:test";
 
 const testDir = realpathSync(
   mkdtempSync(join(tmpdir(), "vellum-cli-test-workspace-")),
@@ -24,4 +24,8 @@ afterAll(() => {
   } catch {
     /* best-effort cleanup */
   }
+
+  // Reset all module mocks so mock.module() calls in one test file
+  // don't leak into the next file in the same bun test run.
+  mock.restore();
 });