@vellumai/cli 0.10.11 → 0.10.12-dev.202607242326.75b9ec6

package/node_modules/@vellumai/service-contracts/src/trust-rules.ts

@@ -0,0 +1,116 @@
+/**
+ * Trust rule types shared between the assistant daemon and the gateway.
+ *
+ * These are extracted from `assistant/src/permissions/types.ts` and
+ * `assistant/src/permissions/trust-store.ts` so that both packages can
+ * reference a single canonical definition.
+ *
+ * Tools are grouped into "families" based on how their permission candidates
+ * are constructed and matched:
+ *
+ * - **Scoped**: tools whose candidates include a filesystem path and obey
+ *   directory-boundary scope constraints (`file_read`, `file_write`,
+ *   `file_edit`, `host_file_read`, `host_file_write`, `host_file_edit`,
+ *   `host_file_transfer`, `bash`, `host_bash`).
+ * - **URL**: tools whose candidates include a URL (`web_fetch`,
+ *   `network_request`).
+ * - **Managed skill**: tools that manage first-party skill packages
+ *   (`scaffold_managed_skill`, `delete_managed_skill`).
+ * - **Skill load**: the `skill_load` tool, which uses a distinct candidate
+ *   namespace (`skill_load:selector` or `skill_load_dynamic:selector`).
+ * - **Generic**: everything else (computer-use tools, UI surface tools,
+ *   recall, skill_execute, etc.).
+ */
+
+// ---------------------------------------------------------------------------
+// Trust decision
+// ---------------------------------------------------------------------------
+
+/** The possible decisions a trust rule can make. */
+export type TrustDecision = "allow" | "deny" | "ask";
+
+// ---------------------------------------------------------------------------
+// Tool family constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Tools whose permission candidates are scoped to a filesystem path and obey
+ * directory-boundary scope constraints.
+ */
+export const SCOPED_TOOLS = [
+  "file_read",
+  "file_write",
+  "file_edit",
+  "host_file_read",
+  "host_file_write",
+  "host_file_edit",
+  "host_file_transfer",
+  "bash",
+  "host_bash",
+] as const;
+
+/**
+ * Tools whose permission candidates include a URL.
+ */
+export const URL_TOOLS = ["web_fetch", "network_request"] as const;
+
+/**
+ * Tools that manage first-party skill packages (scaffold/delete).
+ */
+export const MANAGED_SKILL_TOOLS = [
+  "scaffold_managed_skill",
+  "delete_managed_skill",
+] as const;
+
+/**
+ * The skill_load tool name. Separated from the array constants because
+ * skill_load is a singleton, not a family with multiple members.
+ */
+export const SKILL_LOAD_TOOL = "skill_load" as const;
+
+/** Set for O(1) lookups when classifying tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+const URL_TOOLS_SET: ReadonlySet<string> = new Set(URL_TOOLS);
+const MANAGED_SKILL_TOOLS_SET: ReadonlySet<string> = new Set(
+  MANAGED_SKILL_TOOLS,
+);
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Returns true when the rule's tool belongs to the scoped-tool family. */
+export function isScopedRule(rule: { tool: string }): boolean {
+  return SCOPED_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool belongs to the URL-tool family. */
+export function isUrlRule(rule: { tool: string }): boolean {
+  return URL_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool belongs to the managed-skill-tool family. */
+export function isManagedSkillRule(rule: { tool: string }): boolean {
+  return MANAGED_SKILL_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool is the skill_load tool. */
+export function isSkillLoadRule(rule: { tool: string }): boolean {
+  return rule.tool === SKILL_LOAD_TOOL;
+}
+
+// ---------------------------------------------------------------------------
+// Scope helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the effective scope for any trust rule. Only scoped rules carry a
+ * `scope` field; all other rule families return `"everywhere"`.
+ */
+export function ruleScope(rule: { tool: string; scope?: string }): string {
+  if (isScopedRule(rule)) {
+    return rule.scope ?? "everywhere";
+  }
+  return "everywhere";
+}
+

package/node_modules/@vellumai/service-contracts/src/twilio-ingress.ts

@@ -0,0 +1,73 @@
+import { normalizePublicBaseUrl } from "./ingress.js";
+
+export const TWILIO_VOICE_WEBHOOK_PATH = "/webhooks/twilio/voice";
+export const TWILIO_STATUS_WEBHOOK_PATH = "/webhooks/twilio/status";
+export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
+
+/**
+ * Sentinel placeholder embedded in TwiML by the assistant where the real
+ * public base URL should go. The gateway replaces `wss://__VELLUM_PUBLIC_BASE_URL__/…`
+ * with the actual public URL (from Velay registration, config, or the
+ * `X-Vellum-Ingress-URL` header) before returning TwiML to Twilio.
+ *
+ * The placeholder uses `https://` so that `buildTwilioMediaStreamUrl` can
+ * apply the standard `http→ws` scheme conversion, producing
+ * `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
+ */
+export const TWILIO_PUBLIC_BASE_URL_PLACEHOLDER =
+  "https://__VELLUM_PUBLIC_BASE_URL__";
+
+/**
+ * The WebSocket-scheme form of the placeholder that appears in TwiML after
+ * the `http→ws` scheme conversion applied by the URL builders.
+ */
+export const TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER =
+  "wss://__VELLUM_PUBLIC_BASE_URL__";
+
+export { normalizePublicBaseUrl } from "./ingress.js";
+
+export type TwilioPhoneNumberWebhookUrls = {
+  statusCallbackUrl: string;
+  voiceUrl: string;
+};
+
+export function resolveTwilioPublicBaseUrl(
+  ingress: { publicBaseUrl?: unknown } | undefined,
+  fallbackPublicBaseUrl?: unknown,
+): string | undefined {
+  const publicBaseUrl = normalizePublicBaseUrl(ingress?.publicBaseUrl);
+  if (publicBaseUrl) return publicBaseUrl;
+
+  return normalizePublicBaseUrl(fallbackPublicBaseUrl);
+}
+
+export function buildTwilioVoiceWebhookUrl(
+  baseUrl: string,
+  callSessionId?: string,
+): string {
+  if (callSessionId) {
+    return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}?callSessionId=${callSessionId}`;
+  }
+  return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioStatusWebhookUrl(baseUrl: string): string {
+  return `${baseUrl}${TWILIO_STATUS_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioMediaStreamUrl(baseUrl: string): string {
+  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_MEDIA_STREAM_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioPhoneNumberWebhookUrls(
+  baseUrl: string,
+): TwilioPhoneNumberWebhookUrls {
+  return {
+    statusCallbackUrl: buildTwilioStatusWebhookUrl(baseUrl),
+    voiceUrl: buildTwilioVoiceWebhookUrl(baseUrl),
+  };
+}
+
+function toTwilioWebSocketBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/^http(s?)/, "ws$1");
+}

package/node_modules/@vellumai/service-contracts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11",
+  "version": "0.10.12-dev.202607242326.75b9ec6",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -31,17 +31,21 @@
   "dependencies": {
     "@vellumai/environments": "file:../packages/environments",
     "@vellumai/local-mode": "file:../packages/local-mode",
+    "@vellumai/service-contracts": "file:../packages/service-contracts",
     "chalk": "5.6.2",
     "ink": "6.8.0",
     "nanoid": "5.1.7",
+    "qrcode-terminal": "0.12.0",
     "react": "19.2.4"
   },
   "bundledDependencies": [
     "@vellumai/environments",
-    "@vellumai/local-mode"
+    "@vellumai/local-mode",
+    "@vellumai/service-contracts"
   ],
   "devDependencies": {
     "@types/bun": "1.3.11",
+    "@types/qrcode-terminal": "0.12.2",
     "@types/react": "19.2.14",
     "eslint": "10.1.0",
     "knip": "5.88.1",

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

@@ -1,5 +1,19 @@
-import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  describe,
+  test,
+  expect,
+  beforeEach,
+  afterEach,
+  afterAll,
+  spyOn,
+} from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -16,6 +30,7 @@ import {
   lookupAssistantByIdentifier,
   removeAssistantEntry,
   loadAllAssistants,
+  resolveTargetAssistant,
   saveAssistantEntry,
   getActiveAssistant,
   migrateLegacyEntry,
@@ -700,3 +715,104 @@ describe("env-scoped lockfile and migration", () => {
     }
   });
 });
+
+describe("cross-environment hint on resolution failure", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-config-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env to production so the detector skips it and the hint
+    // copy is deterministic. The current-env lockfile is emptied so resolution
+    // genuinely finds nothing.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    rmSync(join(testDir, ".vellum.lockfile.json"), { force: true });
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the exact split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  function captureResolveTargetAssistantError(): string {
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation(
+      (...args: unknown[]) => {
+        errors.push(args.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      _code?: number,
+    ) => {
+      throw new Error("exit");
+    }) as typeof process.exit);
+    try {
+      expect(() => resolveTargetAssistant()).toThrow("exit");
+    } finally {
+      errorSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+    return errors.join("\n");
+  }
+
+  test("formatAssistantLookupError appends the hint when another env has assistants", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toContain("No assistant found with name or ID 'ghost'.");
+    expect(msg).toContain("Install vellum Command");
+    expect(msg).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("formatAssistantLookupError stays bare when no other env has assistants", () => {
+    // dataHome is empty — detection finds nothing, so the message is intact.
+    const msg = formatAssistantLookupError("ghost", { status: "not_found" });
+    expect(msg).toBe("No assistant found with name or ID 'ghost'.");
+  });
+
+  test("ambiguous lookup never gets the hint", () => {
+    seedDevAssistant();
+    const msg = formatAssistantLookupError("Alice", {
+      status: "ambiguous",
+      matches: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+    expect(msg).not.toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error carries the hint", () => {
+    seedDevAssistant();
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).toContain("Install vellum Command");
+  });
+
+  test("resolveTargetAssistant zero-assistants error stays bare without other envs", () => {
+    const combined = captureResolveTargetAssistantError();
+    expect(combined).toContain("No assistant found. Run 'vellum hatch' first.");
+    expect(combined).not.toContain("Install vellum Command");
+  });
+});

package/src/__tests__/flags.test.ts

@@ -188,14 +188,7 @@ describe("vellum flags --assistant routing", () => {
       ],
       "alice-1",
     );
-    process.argv = [
-      "bun",
-      "vellum",
-      "flags",
-      "set",
-      "voice-mode",
-      "true",
-    ];
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
 
     await flags();
 
@@ -246,3 +239,80 @@ describe("vellum flags --assistant routing", () => {
     expect(fetchCalls.length).toBe(0);
   });
 });
+
+describe("vellum flags cross-environment hint", () => {
+  let xdgDataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    xdgDataHome = mkdtempSync(join(tmpdir(), "cli-flags-hint-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    // Pin production so the detector skips it and the lockfile routes to
+    // testDir; the VELLUM_ENVIRONMENT var beats this machine's env config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+    // An unreachable gateway: every request throws like a dead socket would.
+    // Cast through `unknown` since an always-throwing stub returns
+    // `Promise<never>`, which does not structurally overlap with `fetch`.
+    globalThis.fetch = (async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof globalThis.fetch;
+    process.exit = ((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as typeof process.exit;
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.exit = originalExit;
+    globalThis.fetch = originalFetch;
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(xdgDataHome, { recursive: true, force: true });
+  });
+
+  // A dev-env assistant lives under the dev data dir, invisible to this
+  // production CLI — the split the hint explains.
+  function seedDevAssistant(): void {
+    mkdirSync(join(xdgDataHome, "vellum-dev", "assistants", "dev-bot"), {
+      recursive: true,
+    });
+  }
+
+  test("gateway-unreachable error gains the hint when another env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    seedDevAssistant();
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    await expect(flags()).rejects.toThrow(/Install vellum Command/);
+  });
+
+  test("gateway-unreachable error stays bare when no other env has assistants", async () => {
+    writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
+    // xdgDataHome is empty — detection finds nothing, so the message is intact.
+    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    let error: Error | undefined;
+    try {
+      await flags();
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error?.message).toContain("Could not reach the assistant gateway");
+    expect(error?.message).not.toContain("Install vellum Command");
+  });
+});

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

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Real assistant-config reads the lockfile from VELLUM_LOCKFILE_DIR.
+const testDir = mkdtempSync(join(tmpdir(), "ingress-config-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+import { clearIngressUrl, saveIngressUrl } from "../lib/ingress-config.js";
+
+function writeLockfile(entry: Record<string, unknown>): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({ assistants: [entry], activeAssistant: "ingress-test" }),
+  );
+}
+
+function readLockfileEntry(): Record<string, unknown> {
+  const data = JSON.parse(
+    readFileSync(join(testDir, ".vellum.lock.json"), "utf-8"),
+  ) as { assistants: Record<string, unknown>[] };
+  return data.assistants[0];
+}
+
+const tempDirs: string[] = [];
+
+function makeWorkspace(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ingress-config-ws-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("ingress lockfile mirroring", () => {
+  test("saveIngressUrl stamps the entry's ingressUrl when given an assistantId", () => {
+    writeLockfile({
+      assistantId: "ingress-test",
+      runtimeUrl: "http://192.168.1.50:7830",
+      cloud: "local",
+    });
+    const ws = makeWorkspace();
+
+    saveIngressUrl(ws, "https://tunnel.example.ts.net", "ingress-test");
+
+    // Both contracts are written: workspace config (gateway-facing)...
+    const config = JSON.parse(readFileSync(join(ws, "config.json"), "utf-8"));
+    expect(config.ingress.publicBaseUrl).toBe("https://tunnel.example.ts.net");
+    // ...and the lockfile entry (CLI-facing).
+    expect(readLockfileEntry().ingressUrl).toBe(
+      "https://tunnel.example.ts.net",
+    );
+  });
+
+  test("clearIngressUrl removes the entry's ingressUrl", () => {
+    writeLockfile({
+      assistantId: "ingress-test",
+      runtimeUrl: "http://192.168.1.50:7830",
+      cloud: "local",
+      ingressUrl: "https://tunnel.example.ts.net",
+    });
+    const ws = makeWorkspace();
+    saveIngressUrl(ws, "https://tunnel.example.ts.net");
+
+    clearIngressUrl(ws, "ingress-test");
+
+    const config = JSON.parse(readFileSync(join(ws, "config.json"), "utf-8"));
+    expect(config.ingress.publicBaseUrl).toBeUndefined();
+    expect(readLockfileEntry().ingressUrl).toBeUndefined();
+  });
+
+  test("without an assistantId the lockfile is untouched", () => {
+    writeLockfile({
+      assistantId: "ingress-test",
+      runtimeUrl: "http://192.168.1.50:7830",
+      cloud: "local",
+    });
+    const ws = makeWorkspace();
+
+    saveIngressUrl(ws, "https://tunnel.example.ts.net");
+
+    expect(readLockfileEntry().ingressUrl).toBeUndefined();
+  });
+
+  test("an unknown assistantId is a no-op, not an error", () => {
+    writeLockfile({
+      assistantId: "ingress-test",
+      runtimeUrl: "http://192.168.1.50:7830",
+      cloud: "local",
+    });
+    const ws = makeWorkspace();
+
+    expect(() => {
+      saveIngressUrl(ws, "https://tunnel.example.ts.net", "no-such-assistant");
+    }).not.toThrow();
+    expect(readLockfileEntry().ingressUrl).toBeUndefined();
+  });
+});

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

@@ -1,10 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-} from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";