@vellumai/assistant 0.6.0 → 0.6.2

package/src/avatar/traits-png-sync.ts

@@ -3,7 +3,7 @@ import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir } from "../util/platform.js";
+import { AVATAR_IMAGE_FILENAME, getAvatarDir } from "../util/platform.js";
 import { renderCharacterAscii } from "./ascii-renderer.js";
 import { getCharacterComponents } from "./character-components.js";
 import { renderCharacterPng } from "./png-renderer.js";
@@ -64,7 +64,7 @@ function writeAvatarFiles(
   pngBuffer: Buffer,
   asciiArt: string | null,
 ): boolean {
-  const pngPath = join(avatarDir, "avatar-image.png");
+  const pngPath = join(avatarDir, AVATAR_IMAGE_FILENAME);
   const pngTmp = `${pngPath}.${randomUUID()}.tmp`;
   writeFileSync(pngTmp, pngBuffer);
   renameSync(pngTmp, pngPath);
@@ -144,7 +144,7 @@ export function writeTraitsAndRenderAvatar(
     };
   }
 
-  const avatarDir = join(getWorkspaceDir(), "data", "avatar");
+  const avatarDir = getAvatarDir();
   const traitsPath = join(avatarDir, "character-traits.json");
 
   try {

package/src/channels/types.ts

@@ -90,6 +90,11 @@ export function isInteractiveInterface(id: InterfaceId): boolean {
   return INTERACTIVE_INTERFACES.has(id);
 }
 
+/** Whether the interface supports host proxies (bash, file, computer-use). */
+export function supportsHostProxy(id: InterfaceId): boolean {
+  return id === "macos";
+}
+
 export interface TurnInterfaceContext {
   userMessageInterface: InterfaceId;
   assistantMessageInterface: InterfaceId;

package/src/cli/__tests__/run-assistant-command.ts

@@ -0,0 +1,56 @@
+export interface AssistantCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * CLI test utility — run an assistant CLI command via the real program,
+ * capturing stdout and stderr.
+ *
+ * Returns both stdout and stderr. For backward compatibility, the function
+ * is also callable with just a string return (use `runAssistantCommand`).
+ */
+export async function runAssistantCommandFull(
+  ...args: string[]
+): Promise<AssistantCommandResult> {
+  const { buildCliProgram } = await import("../program.js");
+  const program = await buildCliProgram();
+  program.exitOverride();
+
+  const stderrChunks: string[] = [];
+  program.configureOutput({
+    writeErr: (str: string) => stderrChunks.push(str),
+    writeOut: () => {},
+  });
+
+  const stdoutChunks: string[] = [];
+  const originalWrite = process.stdout.write;
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdoutChunks.push(
+      typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk),
+    );
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    await program.parseAsync(["node", "assistant", ...args]);
+  } catch {
+    /* commander exit override throws */
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+
+  return {
+    stdout: stdoutChunks.join(""),
+    stderr: stderrChunks.join(""),
+  };
+}
+
+/**
+ * CLI test utility — run an assistant CLI command via the real program,
+ * capturing stdout (backward-compatible wrapper).
+ */
+export async function runAssistantCommand(...args: string[]): Promise<string> {
+  const result = await runAssistantCommandFull(...args);
+  return result.stdout;
+}

package/src/cli/__tests__/unknown-command.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "bun:test";
+
+import { runAssistantCommandFull } from "./run-assistant-command.js";
+
+describe("unknown command handling", () => {
+  it("reports an error for an unknown subcommand", async () => {
+    const { stderr } = await runAssistantCommandFull("invalid");
+
+    expect(stderr).toContain("unknown command 'invalid'");
+    expect(stderr).toContain("Run 'assistant --help'");
+  });
+
+  it("reports an error for an unknown subcommand with extra arguments", async () => {
+    const { stderr } = await runAssistantCommandFull("invalid", "something");
+
+    expect(stderr).toContain("unknown command 'invalid'");
+    expect(stderr).toContain("Run 'assistant --help'");
+  });
+
+  it("suggests a similar command when the input is close", async () => {
+    const { stderr } = await runAssistantCommandFull("confg");
+
+    expect(stderr).toContain("unknown command 'confg'");
+    expect(stderr).toContain("Did you mean 'config'");
+  });
+
+  it("does not suggest a command when the input is too far off", async () => {
+    const { stderr } = await runAssistantCommandFull("xyzzy");
+
+    expect(stderr).toContain("unknown command 'xyzzy'");
+    expect(stderr).not.toContain("Did you mean");
+  });
+});

package/src/cli/commands/__tests__/email-download.test.ts

@@ -0,0 +1,245 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  getMockFetchCalls,
+  mockFetch,
+  resetMockFetch,
+} from "../../../__tests__/mock-fetch.js";
+import { _setOverridesForTesting } from "../../../config/assistant-feature-flags.js";
+import { setPlatformAssistantId } from "../../../config/env.js";
+import { credentialKey } from "../../../security/credential-key.js";
+import {
+  _resetBackend,
+  deleteSecureKeyAsync,
+  setSecureKeyAsync,
+} from "../../../security/secure-keys.js";
+import { runAssistantCommand } from "../../__tests__/run-assistant-command.js";
+
+const ASSISTANT_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+const MESSAGE_ID = "msg-001";
+const API_KEY_CREDENTIAL = credentialKey("vellum", "assistant_api_key");
+
+const SAMPLE_MESSAGE = {
+  id: MESSAGE_ID,
+  direction: "inbound",
+  from_address: "user@example.com",
+  to_addresses: ["mybot@vellum.me"],
+  subject: "Hello bot",
+  body_text: "Hi, this is a test message.",
+  body_html: "<p>Hi, this is a <b>test</b> message.</p>",
+  in_reply_to: "",
+  references: [],
+  created_at: "2026-04-05T12:00:00Z",
+};
+
+function mockDetailSuccess(msg = SAMPLE_MESSAGE, status = 200): void {
+  mockFetch(`/emails/${msg.id}/`, {}, { body: msg, status });
+}
+
+let savedCesUrl: string | undefined;
+let savedContainerized: string | undefined;
+let tmpOutputPath: string;
+
+beforeEach(async () => {
+  process.exitCode = 0;
+
+  savedCesUrl = process.env.CES_CREDENTIAL_URL;
+  savedContainerized = process.env.IS_CONTAINERIZED;
+  delete process.env.CES_CREDENTIAL_URL;
+  delete process.env.IS_CONTAINERIZED;
+
+  _resetBackend();
+  resetMockFetch();
+  _setOverridesForTesting({ "email-channel": true });
+  setPlatformAssistantId(ASSISTANT_ID);
+  await setSecureKeyAsync(API_KEY_CREDENTIAL, "test-api-key");
+
+  tmpOutputPath = join(tmpdir(), `email-download-test-${Date.now()}.txt`);
+});
+
+afterEach(() => {
+  resetMockFetch();
+  _setOverridesForTesting({});
+  setPlatformAssistantId(undefined);
+  _resetBackend();
+
+  if (savedCesUrl !== undefined) process.env.CES_CREDENTIAL_URL = savedCesUrl;
+  else delete process.env.CES_CREDENTIAL_URL;
+  if (savedContainerized !== undefined)
+    process.env.IS_CONTAINERIZED = savedContainerized;
+  else delete process.env.IS_CONTAINERIZED;
+
+  if (existsSync(tmpOutputPath)) rmSync(tmpOutputPath);
+});
+
+describe("assistant email download", () => {
+  test("default format shows headers and plain-text body", async () => {
+    mockDetailSuccess();
+
+    const output = await runAssistantCommand("email", "download", MESSAGE_ID);
+
+    expect(output).toContain("From:    user@example.com");
+    expect(output).toContain("To:      mybot@vellum.me");
+    expect(output).toContain("Subject: Hello bot");
+    expect(output).toContain("Hi, this is a test message.");
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("--format json returns full message object", async () => {
+    mockDetailSuccess();
+
+    const output = await runAssistantCommand(
+      "email",
+      "download",
+      MESSAGE_ID,
+      "--format",
+      "json",
+    );
+
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.id).toBe(MESSAGE_ID);
+    expect(parsed.body_text).toBe("Hi, this is a test message.");
+    expect(parsed.body_html).toContain("<b>test</b>");
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("--json flag also returns JSON", async () => {
+    mockDetailSuccess();
+
+    const output = await runAssistantCommand(
+      "email",
+      "--json",
+      "download",
+      MESSAGE_ID,
+    );
+
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.id).toBe(MESSAGE_ID);
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("--format html returns HTML body", async () => {
+    mockDetailSuccess();
+
+    const output = await runAssistantCommand(
+      "email",
+      "download",
+      MESSAGE_ID,
+      "--format",
+      "html",
+    );
+
+    expect(output).toContain("<p>Hi, this is a <b>test</b> message.</p>");
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("--format html with no HTML body returns error", async () => {
+    mockDetailSuccess({ ...SAMPLE_MESSAGE, body_html: "" });
+
+    const output = await runAssistantCommand(
+      "email",
+      "download",
+      MESSAGE_ID,
+      "--format",
+      "html",
+    );
+
+    expect(process.exitCode).toBe(1);
+    // stderr output from log.error, but stdout may be empty — check exitCode
+    expect(output).not.toContain("<p>");
+  });
+
+  test("--output writes to file", async () => {
+    mockDetailSuccess();
+
+    await runAssistantCommand(
+      "email",
+      "download",
+      MESSAGE_ID,
+      "-o",
+      tmpOutputPath,
+    );
+
+    expect(process.exitCode).toBe(0);
+    expect(existsSync(tmpOutputPath)).toBe(true);
+    const content = readFileSync(tmpOutputPath, "utf-8");
+    expect(content).toContain("From:    user@example.com");
+    expect(content).toContain("Hi, this is a test message.");
+  });
+
+  test("calls correct URL", async () => {
+    mockDetailSuccess();
+
+    await runAssistantCommand("email", "download", MESSAGE_ID);
+
+    const calls = getMockFetchCalls();
+    expect(calls).toHaveLength(1);
+    expect(calls[0].path).toContain(
+      `/v1/assistants/${ASSISTANT_ID}/emails/${MESSAGE_ID}/`,
+    );
+  });
+
+  test("404 returns error", async () => {
+    mockFetch(
+      `/emails/${MESSAGE_ID}/`,
+      {},
+      { body: { detail: "Not found." }, status: 404 },
+    );
+
+    const output = await runAssistantCommand(
+      "email",
+      "--json",
+      "download",
+      MESSAGE_ID,
+    );
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Not found");
+  });
+
+  test("missing platform credentials returns error", async () => {
+    await deleteSecureKeyAsync(API_KEY_CREDENTIAL);
+
+    const output = await runAssistantCommand(
+      "email",
+      "--json",
+      "download",
+      MESSAGE_ID,
+    );
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Platform credentials not configured");
+  });
+
+  test("missing assistant ID returns error", async () => {
+    setPlatformAssistantId("");
+
+    const output = await runAssistantCommand(
+      "email",
+      "--json",
+      "download",
+      MESSAGE_ID,
+    );
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Assistant ID");
+  });
+
+  test("in_reply_to header shown when present", async () => {
+    mockDetailSuccess({
+      ...SAMPLE_MESSAGE,
+      in_reply_to: "<orig@mail.gmail.com>",
+    });
+
+    const output = await runAssistantCommand("email", "download", MESSAGE_ID);
+
+    expect(output).toContain("In-Reply-To: <orig@mail.gmail.com>");
+    expect(process.exitCode).toBe(0);
+  });
+});

package/src/cli/commands/__tests__/email-list.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  getMockFetchCalls,
+  mockFetch,
+  resetMockFetch,
+} from "../../../__tests__/mock-fetch.js";
+import { _setOverridesForTesting } from "../../../config/assistant-feature-flags.js";
+import { setPlatformAssistantId } from "../../../config/env.js";
+import { credentialKey } from "../../../security/credential-key.js";
+import {
+  _resetBackend,
+  deleteSecureKeyAsync,
+  setSecureKeyAsync,
+} from "../../../security/secure-keys.js";
+import { runAssistantCommand } from "../../__tests__/run-assistant-command.js";
+
+const ASSISTANT_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+const API_KEY_CREDENTIAL = credentialKey("vellum", "assistant_api_key");
+
+const SAMPLE_MESSAGES = [
+  {
+    id: "msg-001",
+    direction: "inbound",
+    from_address: "user@example.com",
+    to_addresses: ["mybot@vellum.me"],
+    subject: "Hello bot",
+    created_at: "2026-04-05T12:00:00Z",
+  },
+  {
+    id: "msg-002",
+    direction: "outbound",
+    from_address: "mybot@vellum.me",
+    to_addresses: ["user@example.com"],
+    subject: "Re: Hello bot",
+    created_at: "2026-04-05T12:01:00Z",
+  },
+];
+
+function mockListEmails(
+  results = SAMPLE_MESSAGES,
+  count?: number,
+  status = 200,
+): void {
+  mockFetch(
+    "/emails/",
+    {},
+    { body: { results, count: count ?? results.length }, status },
+  );
+}
+
+let savedCesUrl: string | undefined;
+let savedContainerized: string | undefined;
+
+beforeEach(async () => {
+  process.exitCode = 0;
+
+  savedCesUrl = process.env.CES_CREDENTIAL_URL;
+  savedContainerized = process.env.IS_CONTAINERIZED;
+  delete process.env.CES_CREDENTIAL_URL;
+  delete process.env.IS_CONTAINERIZED;
+
+  _resetBackend();
+  resetMockFetch();
+  _setOverridesForTesting({ "email-channel": true });
+  setPlatformAssistantId(ASSISTANT_ID);
+  await setSecureKeyAsync(API_KEY_CREDENTIAL, "test-api-key");
+});
+
+afterEach(() => {
+  resetMockFetch();
+  _setOverridesForTesting({});
+  setPlatformAssistantId(undefined);
+  _resetBackend();
+
+  if (savedCesUrl !== undefined) process.env.CES_CREDENTIAL_URL = savedCesUrl;
+  else delete process.env.CES_CREDENTIAL_URL;
+  if (savedContainerized !== undefined)
+    process.env.IS_CONTAINERIZED = savedContainerized;
+  else delete process.env.IS_CONTAINERIZED;
+});
+
+describe("assistant email list", () => {
+  test("--json returns messages and count", async () => {
+    mockListEmails();
+
+    const output = await runAssistantCommand("email", "--json", "list");
+
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.results).toHaveLength(2);
+    expect(parsed.count).toBe(2);
+    expect(parsed.results[0].subject).toBe("Hello bot");
+    expect(parsed.results[1].direction).toBe("outbound");
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("calls correct URL with no filters", async () => {
+    mockListEmails();
+
+    await runAssistantCommand("email", "--json", "list");
+
+    const calls = getMockFetchCalls();
+    expect(calls).toHaveLength(1);
+    expect(calls[0].path).toContain(`/v1/assistants/${ASSISTANT_ID}/emails/`);
+    // Default limit=20 should be in query string
+    expect(calls[0].path).toContain("limit=20");
+  });
+
+  test("--direction filters by direction", async () => {
+    mockListEmails();
+
+    await runAssistantCommand(
+      "email",
+      "--json",
+      "list",
+      "--direction",
+      "inbound",
+    );
+
+    const calls = getMockFetchCalls();
+    expect(calls[0].path).toContain("direction=inbound");
+  });
+
+  test("--limit sets result count", async () => {
+    mockListEmails();
+
+    await runAssistantCommand("email", "--json", "list", "--limit", "5");
+
+    const calls = getMockFetchCalls();
+    expect(calls[0].path).toContain("limit=5");
+  });
+
+  test("--since filters by date", async () => {
+    mockListEmails();
+
+    await runAssistantCommand(
+      "email",
+      "--json",
+      "list",
+      "--since",
+      "2026-04-01",
+    );
+
+    const calls = getMockFetchCalls();
+    expect(calls[0].path).toContain("since=2026-04-01");
+  });
+
+  test("empty results returns empty array", async () => {
+    mockListEmails([], 0);
+
+    const output = await runAssistantCommand("email", "--json", "list");
+
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.results).toHaveLength(0);
+    expect(parsed.count).toBe(0);
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("endpoint failure returns error", async () => {
+    mockFetch(
+      "/emails/",
+      {},
+      { body: { detail: "Internal server error" }, status: 500 },
+    );
+
+    const output = await runAssistantCommand("email", "--json", "list");
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Internal server error");
+  });
+
+  test("missing platform credentials returns error", async () => {
+    await deleteSecureKeyAsync(API_KEY_CREDENTIAL);
+
+    const output = await runAssistantCommand("email", "--json", "list");
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Platform credentials not configured");
+  });
+
+  test("missing assistant ID returns error", async () => {
+    setPlatformAssistantId("");
+
+    const output = await runAssistantCommand("email", "--json", "list");
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.error).toContain("Assistant ID");
+  });
+});