@vellumai/cli 0.12.4 → 0.12.5-dev.202609250721.20229d0

package/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -67,8 +67,31 @@ describe("notificationAvatarDiscHex", () => {
 });
 
 describe("notificationAvatarSvg", () => {
+  test("fills the entire circular crop with a custom image", () => {
+    const svg = notificationAvatarSvg({
+      kind: "image",
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(attributes("image", svg)).toMatchObject({
+      x: "0",
+      y: "0",
+      width: "256",
+      height: "256",
+      preserveAspectRatio: "xMidYMid slice",
+      "clip-path": "url(#notification-avatar-disc)",
+    });
+    expect(allAttributes("circle", svg)[1]).toEqual({
+      cx: "128",
+      cy: "128",
+      r: "128",
+    });
+  });
+
   test("draws one disc and one inset avatar at the default size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -100,6 +123,7 @@ describe("notificationAvatarSvg", () => {
     // upload fill the square instead of letterboxing is the pair of attributes
     // asserted here.
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -121,6 +145,7 @@ describe("notificationAvatarSvg", () => {
 
   test("scales the geometry to a custom size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
       size: 100,
@@ -142,6 +167,7 @@ describe("notificationAvatarSvg", () => {
 
   test("carries a non-PNG inner raster with its own media type", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       innerMediaType: "image/jpeg",
       accentHex: "#E9642F",
@@ -154,6 +180,7 @@ describe("notificationAvatarSvg", () => {
 
   test("paints the fallback disc when there is no accent", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
     });
@@ -164,8 +191,21 @@ describe("notificationAvatarSvg", () => {
 });
 
 describe("notificationAvatarGeometry", () => {
+  test("custom images reach the disc edge at any output size", () => {
+    expect(notificationAvatarGeometry("image")).toEqual({
+      radius: 128,
+      offset: 0,
+      inner: 256,
+    });
+    expect(notificationAvatarGeometry("image", 100)).toEqual({
+      radius: 50,
+      offset: 0,
+      inner: 100,
+    });
+  });
+
   test("derives the disc, the border and the avatar edge from the size", () => {
-    expect(notificationAvatarGeometry(100)).toEqual({
+    expect(notificationAvatarGeometry("character", 100)).toEqual({
       radius: 50,
       offset: 11,
       inner: 78,
@@ -173,15 +213,19 @@ describe("notificationAvatarGeometry", () => {
   });
 
   test("measures the default size when given none", () => {
-    expect(notificationAvatarGeometry()).toEqual(
-      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    expect(notificationAvatarGeometry("character")).toEqual(
+      notificationAvatarGeometry("character", NOTIFICATION_AVATAR_SIZE),
     );
   });
 
   test("is the geometry the SVG is drawn with", () => {
     const size = 100;
-    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const { radius, offset, inner } = notificationAvatarGeometry(
+      "character",
+      size,
+    );
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
       size,

package/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -15,11 +15,12 @@
  */
 
 import { isAvatarAccentHex } from "./accent.js";
+import type { AvatarKind } from "./manifest.js";
 
 /** Output edge in pixels: large enough for an iOS notification thumbnail. */
 export const NOTIFICATION_AVATAR_SIZE = 256;
 
-/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+/** Free disc on each side of a character avatar, as a fraction of the edge. */
 export const NOTIFICATION_AVATAR_INSET = 0.11;
 
 /** The disc when the assistant has no accent. */
@@ -48,7 +49,7 @@ export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
  * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
  * a disc rendered by an older spec even when the avatar itself is unchanged.
  */
-export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 2;
 
 /** The id the inner raster's clip path is referenced by inside the document. */
 const CLIP_ID = "notification-avatar-disc";
@@ -74,24 +75,26 @@ export function notificationAvatarDiscHex(accentHex: string | null): string {
 
 /** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
 export type NotificationAvatarMediaType =
-  | "image/png"
-  | "image/jpeg"
-  | "image/gif";
+  "image/png" | "image/jpeg" | "image/gif";
 
 /**
  * The three measurements the drawing derives from the edge: the disc's radius,
  * which is also its centre; the free border around the avatar; and the
  * avatar's own edge. Every rasterizer reads them from here, so the daemon's
  * SVG and the desktop canvas cannot drift.
+ * Custom images fill the disc; character avatars retain space around their
+ * silhouette.
  */
 export function notificationAvatarGeometry(
+  kind: Exclude<AvatarKind, "none">,
   size: number = NOTIFICATION_AVATAR_SIZE,
 ): { radius: number; offset: number; inner: number } {
-  const offset = size * NOTIFICATION_AVATAR_INSET;
+  const offset = kind === "character" ? size * NOTIFICATION_AVATAR_INSET : 0;
   return { radius: size / 2, offset, inner: size - 2 * offset };
 }
 
 export interface NotificationAvatarSvgOptions {
+  kind: Exclude<AvatarKind, "none">;
   /** The avatar raster to draw inside the disc, base64 with no data prefix. */
   innerPngBase64: string;
   /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
@@ -107,7 +110,7 @@ function px(value: number): string {
 
 /**
  * The notification avatar as an SVG document: a filled disc with the avatar
- * drawn inset into it.
+ * filling it for custom images or inset for character avatars.
  *
  * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
  * canvas does, so a portrait or landscape upload fills the square instead of
@@ -119,12 +122,13 @@ function px(value: number): string {
  * rasterizer is known to render it.
  */
 export function notificationAvatarSvg({
+  kind,
   innerPngBase64,
   innerMediaType = "image/png",
   accentHex,
   size = NOTIFICATION_AVATAR_SIZE,
 }: NotificationAvatarSvgOptions): string {
-  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const { radius, offset, inner } = notificationAvatarGeometry(kind, size);
   const href = `data:${innerMediaType};base64,${innerPngBase64}`;
   const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
   return (

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -67,8 +67,31 @@ describe("notificationAvatarDiscHex", () => {
 });
 
 describe("notificationAvatarSvg", () => {
+  test("fills the entire circular crop with a custom image", () => {
+    const svg = notificationAvatarSvg({
+      kind: "image",
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(attributes("image", svg)).toMatchObject({
+      x: "0",
+      y: "0",
+      width: "256",
+      height: "256",
+      preserveAspectRatio: "xMidYMid slice",
+      "clip-path": "url(#notification-avatar-disc)",
+    });
+    expect(allAttributes("circle", svg)[1]).toEqual({
+      cx: "128",
+      cy: "128",
+      r: "128",
+    });
+  });
+
   test("draws one disc and one inset avatar at the default size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -100,6 +123,7 @@ describe("notificationAvatarSvg", () => {
     // upload fill the square instead of letterboxing is the pair of attributes
     // asserted here.
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -121,6 +145,7 @@ describe("notificationAvatarSvg", () => {
 
   test("scales the geometry to a custom size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
       size: 100,
@@ -142,6 +167,7 @@ describe("notificationAvatarSvg", () => {
 
   test("carries a non-PNG inner raster with its own media type", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       innerMediaType: "image/jpeg",
       accentHex: "#E9642F",
@@ -154,6 +180,7 @@ describe("notificationAvatarSvg", () => {
 
   test("paints the fallback disc when there is no accent", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
     });
@@ -164,8 +191,21 @@ describe("notificationAvatarSvg", () => {
 });
 
 describe("notificationAvatarGeometry", () => {
+  test("custom images reach the disc edge at any output size", () => {
+    expect(notificationAvatarGeometry("image")).toEqual({
+      radius: 128,
+      offset: 0,
+      inner: 256,
+    });
+    expect(notificationAvatarGeometry("image", 100)).toEqual({
+      radius: 50,
+      offset: 0,
+      inner: 100,
+    });
+  });
+
   test("derives the disc, the border and the avatar edge from the size", () => {
-    expect(notificationAvatarGeometry(100)).toEqual({
+    expect(notificationAvatarGeometry("character", 100)).toEqual({
       radius: 50,
       offset: 11,
       inner: 78,
@@ -173,15 +213,19 @@ describe("notificationAvatarGeometry", () => {
   });
 
   test("measures the default size when given none", () => {
-    expect(notificationAvatarGeometry()).toEqual(
-      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    expect(notificationAvatarGeometry("character")).toEqual(
+      notificationAvatarGeometry("character", NOTIFICATION_AVATAR_SIZE),
     );
   });
 
   test("is the geometry the SVG is drawn with", () => {
     const size = 100;
-    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const { radius, offset, inner } = notificationAvatarGeometry(
+      "character",
+      size,
+    );
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
       size,

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -15,11 +15,12 @@
  */
 
 import { isAvatarAccentHex } from "./accent.js";
+import type { AvatarKind } from "./manifest.js";
 
 /** Output edge in pixels: large enough for an iOS notification thumbnail. */
 export const NOTIFICATION_AVATAR_SIZE = 256;
 
-/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+/** Free disc on each side of a character avatar, as a fraction of the edge. */
 export const NOTIFICATION_AVATAR_INSET = 0.11;
 
 /** The disc when the assistant has no accent. */
@@ -48,7 +49,7 @@ export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
  * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
  * a disc rendered by an older spec even when the avatar itself is unchanged.
  */
-export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 2;
 
 /** The id the inner raster's clip path is referenced by inside the document. */
 const CLIP_ID = "notification-avatar-disc";
@@ -74,24 +75,26 @@ export function notificationAvatarDiscHex(accentHex: string | null): string {
 
 /** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
 export type NotificationAvatarMediaType =
-  | "image/png"
-  | "image/jpeg"
-  | "image/gif";
+  "image/png" | "image/jpeg" | "image/gif";
 
 /**
  * The three measurements the drawing derives from the edge: the disc's radius,
  * which is also its centre; the free border around the avatar; and the
  * avatar's own edge. Every rasterizer reads them from here, so the daemon's
  * SVG and the desktop canvas cannot drift.
+ * Custom images fill the disc; character avatars retain space around their
+ * silhouette.
  */
 export function notificationAvatarGeometry(
+  kind: Exclude<AvatarKind, "none">,
   size: number = NOTIFICATION_AVATAR_SIZE,
 ): { radius: number; offset: number; inner: number } {
-  const offset = size * NOTIFICATION_AVATAR_INSET;
+  const offset = kind === "character" ? size * NOTIFICATION_AVATAR_INSET : 0;
   return { radius: size / 2, offset, inner: size - 2 * offset };
 }
 
 export interface NotificationAvatarSvgOptions {
+  kind: Exclude<AvatarKind, "none">;
   /** The avatar raster to draw inside the disc, base64 with no data prefix. */
   innerPngBase64: string;
   /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
@@ -107,7 +110,7 @@ function px(value: number): string {
 
 /**
  * The notification avatar as an SVG document: a filled disc with the avatar
- * drawn inset into it.
+ * filling it for custom images or inset for character avatars.
  *
  * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
  * canvas does, so a portrait or landscape upload fills the square instead of
@@ -119,12 +122,13 @@ function px(value: number): string {
  * rasterizer is known to render it.
  */
 export function notificationAvatarSvg({
+  kind,
   innerPngBase64,
   innerMediaType = "image/png",
   accentHex,
   size = NOTIFICATION_AVATAR_SIZE,
 }: NotificationAvatarSvgOptions): string {
-  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const { radius, offset, inner } = notificationAvatarGeometry(kind, size);
   const href = `data:${innerMediaType};base64,${innerPngBase64}`;
   const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
   return (

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/__tests__/guardian-requests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  GUARDIAN_DECISION_ACTION_IDS,
+  isDenyingGuardianAction,
+  isParkGuardianAction,
+} from "../guardian-requests.js";
+
+describe("guardian decision actions", () => {
+  test("reject, leave_unverified and block deny; every other action approves", () => {
+    const denying = GUARDIAN_DECISION_ACTION_IDS.filter(
+      isDenyingGuardianAction,
+    );
+    expect(denying).toEqual(["reject", "leave_unverified", "block"]);
+  });
+
+  test("only leave_unverified parks the sender", () => {
+    const parking = GUARDIAN_DECISION_ACTION_IDS.filter(isParkGuardianAction);
+    expect(parking).toEqual(["leave_unverified"]);
+  });
+
+  test("an absent or unknown action neither denies nor parks", () => {
+    expect(isDenyingGuardianAction(undefined)).toBe(false);
+    expect(isParkGuardianAction("approve_always")).toBe(false);
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -1,7 +1,8 @@
 /**
- * Canonical vocabulary for a guardian request's lifecycle status, shared by
- * the gateway that owns the request rows, the daemon that decides and
- * projects them, and the web that renders the projection.
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
  */
 import { z } from "zod";
 
@@ -16,3 +17,76 @@ export const GuardianRequestStatusSchema = z.enum(
   GUARDIAN_REQUEST_STATUS_VALUES,
 );
 export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `approve_once` / `reject` are the generic decision pair used by every
+ * request kind. `trust` / `verify_code` / `leave_unverified` / `block` are the
+ * introduction-card actions, valid only for `access_request` requests.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;

package/node_modules/@vellumai/service-contracts/src/__tests__/guardian-requests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  GUARDIAN_DECISION_ACTION_IDS,
+  isDenyingGuardianAction,
+  isParkGuardianAction,
+} from "../guardian-requests.js";
+
+describe("guardian decision actions", () => {
+  test("reject, leave_unverified and block deny; every other action approves", () => {
+    const denying = GUARDIAN_DECISION_ACTION_IDS.filter(
+      isDenyingGuardianAction,
+    );
+    expect(denying).toEqual(["reject", "leave_unverified", "block"]);
+  });
+
+  test("only leave_unverified parks the sender", () => {
+    const parking = GUARDIAN_DECISION_ACTION_IDS.filter(isParkGuardianAction);
+    expect(parking).toEqual(["leave_unverified"]);
+  });
+
+  test("an absent or unknown action neither denies nor parks", () => {
+    expect(isDenyingGuardianAction(undefined)).toBe(false);
+    expect(isParkGuardianAction("approve_always")).toBe(false);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -1,7 +1,8 @@
 /**
- * Canonical vocabulary for a guardian request's lifecycle status, shared by
- * the gateway that owns the request rows, the daemon that decides and
- * projects them, and the web that renders the projection.
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
  */
 import { z } from "zod";
 
@@ -16,3 +17,76 @@ export const GuardianRequestStatusSchema = z.enum(
   GUARDIAN_REQUEST_STATUS_VALUES,
 );
 export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `approve_once` / `reject` are the generic decision pair used by every
+ * request kind. `trust` / `verify_code` / `leave_unverified` / `block` are the
+ * introduction-card actions, valid only for `access_request` requests.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.12.4",
+  "version": "0.12.5-dev.202609250721.20229d0",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/debug-bundle.test.ts

@@ -0,0 +1,257 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Lockfile isolation (mirrors backup.test.ts)
+const testDir = mkdtempSync(join(tmpdir(), "cli-debug-bundle-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+import * as assistantConfig from "../lib/assistant-config.js";
+import * as guardianToken from "../lib/guardian-token.js";
+import * as localRuntimeClient from "../lib/local-runtime-client.js";
+import * as platformClient from "../lib/platform-client.js";
+
+const resolveTargetMock = spyOn(
+  assistantConfig,
+  "resolveTargetAssistant",
+).mockImplementation(() => {
+  throw new Error("process.exit:1");
+});
+const readPlatformTokenMock = spyOn(
+  platformClient,
+  "readPlatformToken",
+).mockReturnValue("platform-token");
+const exportMock = spyOn(
+  localRuntimeClient,
+  "localRuntimeExportToGcs",
+).mockResolvedValue({ jobId: "job-1" });
+const identityMock = spyOn(
+  localRuntimeClient,
+  "localRuntimeIdentity",
+).mockResolvedValue({ version: "0.12.3" });
+const pollMock = spyOn(
+  localRuntimeClient,
+  "localRuntimePollJobStatus",
+).mockResolvedValue({
+  jobId: "job-1",
+  type: "export",
+  status: "complete",
+} as unknown as Awaited<
+  ReturnType<typeof localRuntimeClient.localRuntimePollJobStatus>
+>);
+const loadGuardianTokenSpy = spyOn(
+  guardianToken,
+  "loadGuardianToken",
+).mockReturnValue({
+  accessToken: "local-token",
+  accessTokenExpiresAt: new Date(Date.now() + 10 * 60_000).toISOString(),
+} as unknown as ReturnType<typeof guardianToken.loadGuardianToken>);
+const leaseGuardianTokenSpy = spyOn(
+  guardianToken,
+  "leaseGuardianToken",
+).mockResolvedValue({
+  accessToken: "leased-token",
+  accessTokenExpiresAt: new Date(Date.now() + 10 * 60_000).toISOString(),
+} as unknown as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>);
+
+const { debugBundle } = await import("../commands/debug-bundle.js");
+
+const LOCAL_ENTRY = {
+  name: "mine",
+  assistantId: "local-asst-1",
+  runtimeUrl: "http://127.0.0.1:7821",
+  cloud: "local",
+  species: "local",
+  hatchedAt: new Date().toISOString(),
+  platformAssistantId: "11111111-2222-3333-4444-555555555555",
+  platformBaseUrl: "https://platform.vellum.ai",
+  platformOrganizationId: "org-1",
+} as unknown as assistantConfig.AssistantEntry;
+
+let originalFetch: typeof globalThis.fetch;
+let originalExit: typeof process.exit;
+let fetchCalls: { url: string; init?: RequestInit }[] = [];
+let uploadUrlStatus = 201;
+
+beforeEach(() => {
+  process.argv = ["bun", "vellum", "debug-bundle"];
+  originalFetch = globalThis.fetch;
+  originalExit = process.exit;
+  process.exit = mock((code?: number) => {
+    throw new Error(`process.exit:${code}`);
+  }) as unknown as typeof process.exit;
+  fetchCalls = [];
+  uploadUrlStatus = 201;
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      fetchCalls.push({ url: String(input), init });
+      return new Response(
+        JSON.stringify({ url: "https://storage.googleapis.com/b/signed" }),
+        {
+          status: uploadUrlStatus,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    },
+  ) as unknown as typeof globalThis.fetch;
+  resolveTargetMock.mockReset();
+  resolveTargetMock.mockReturnValue(LOCAL_ENTRY);
+  identityMock.mockReset();
+  identityMock.mockResolvedValue({ version: "0.12.3" });
+  leaseGuardianTokenSpy.mockClear();
+  readPlatformTokenMock.mockReset();
+  readPlatformTokenMock.mockReturnValue("platform-token");
+  exportMock.mockClear();
+  pollMock.mockClear();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  process.exit = originalExit;
+});
+
+afterAll(() => {
+  resolveTargetMock.mockRestore();
+  identityMock.mockRestore();
+  leaseGuardianTokenSpy.mockRestore();
+  readPlatformTokenMock.mockRestore();
+  exportMock.mockRestore();
+  pollMock.mockRestore();
+  loadGuardianTokenSpy.mockRestore();
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("vellum debug-bundle", () => {
+  test("mints the URL on the platform, exports with the debug profile, and waits", async () => {
+    await debugBundle();
+
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toBe(
+      "https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/debug-bundle-upload-url/",
+    );
+    expect(fetchCalls[0].init?.method).toBe("POST");
+    expect(
+      (fetchCalls[0].init?.headers as Record<string, string>)[
+        "Vellum-Organization-Id"
+      ],
+    ).toBe("org-1");
+
+    expect(exportMock).toHaveBeenCalledTimes(1);
+    const [entry, token, params] = exportMock.mock.calls[0];
+    expect(entry).toBe(LOCAL_ENTRY);
+    expect(token).toBe("local-token");
+    expect(params).toEqual({
+      uploadUrl: "https://storage.googleapis.com/b/signed",
+      description: "debug bundle for Vellum staff",
+      profile: "debug",
+    });
+    expect(pollMock).toHaveBeenCalled();
+    // The daemon was checked for the debug profile before the platform call.
+    expect(identityMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("passes an unquoted multi-word display name through to the shared resolver", async () => {
+    process.argv = ["bun", "vellum", "debug-bundle", "Support", "Bot"];
+    await debugBundle();
+    expect(resolveTargetMock).toHaveBeenCalledWith("Support Bot");
+  });
+
+  test("refuses a daemon older than the debug profile before any URL is minted", async () => {
+    // Such a daemon strips `profile` and would upload the owner's
+    // credentials to the staff bucket.
+    identityMock.mockResolvedValue({ version: "0.12.2" });
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("0.12.3");
+    expect(fetchCalls).toHaveLength(0);
+    expect(exportMock).not.toHaveBeenCalled();
+  });
+
+  test("re-leases the guardian token when the daemon answers 401 mid-poll", async () => {
+    pollMock.mockReset();
+    let polls = 0;
+    pollMock.mockImplementation(async (_entry, token) => {
+      polls += 1;
+      if (polls === 1) {
+        throw new Error("Local job status check failed: 401 Unauthorized");
+      }
+      expect(token).toBe("leased-token");
+      return {
+        jobId: "job-1",
+        type: "export",
+        status: "complete",
+      } as unknown as Awaited<
+        ReturnType<typeof localRuntimeClient.localRuntimePollJobStatus>
+      >;
+    });
+
+    await debugBundle();
+
+    expect(leaseGuardianTokenSpy).toHaveBeenCalledTimes(1);
+    expect(polls).toBe(2);
+  });
+
+  test("explains what to turn on when the platform refuses", async () => {
+    uploadUrlStatus = 403;
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("Allow Staff Access");
+    expect(exportMock).not.toHaveBeenCalled();
+  });
+
+  test("refuses a Vellum-hosted assistant, which needs no bundle", async () => {
+    resolveTargetMock.mockReturnValue({
+      ...LOCAL_ENTRY,
+      cloud: "vellum",
+    } as unknown as assistantConfig.AssistantEntry);
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("asks for a login when the assistant is not registered", async () => {
+    resolveTargetMock.mockReturnValue({
+      ...LOCAL_ENTRY,
+      platformAssistantId: undefined,
+    } as unknown as assistantConfig.AssistantEntry);
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("vellum login");
+    expect(fetchCalls).toHaveLength(0);
+  });
+});

package/src/commands/debug-bundle.ts

@@ -0,0 +1,221 @@
+/**
+ * `vellum debug-bundle [name]`
+ *
+ * Send Vellum staff a debug bundle of a self-hosted assistant: the
+ * workspace, its logs, and the gateway's own database, with no credentials.
+ * Staff open it on a throwaway debug clone. The platform only hands out the
+ * upload URL while "Allow Staff Access" is on, and the bundle is deleted
+ * after seven days.
+ *
+ * Steps: the daemon is checked for the debug profile, the platform mints
+ * the upload URL, the daemon exports with the debug profile, and this
+ * command waits for the job so the result is real.
+ */
+import {
+  formatAssistantReference,
+  resolveTargetAssistant,
+} from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
+import { pollJobUntilDone } from "../lib/job-polling.js";
+import {
+  MigrationInProgressError,
+  localRuntimeExportToGcs,
+  localRuntimeIdentity,
+  localRuntimePollJobStatus,
+} from "../lib/local-runtime-client.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import {
+  authHeaders,
+  authHeadersForKnownOrganization,
+  getPlatformUrl,
+  readPlatformToken,
+} from "../lib/platform-client.js";
+import { compareVersions } from "../lib/version-compat.js";
+
+// Matches the daemon's own upload deadline (EXPORT_TO_GCS_PUT_TIMEOUT_MS in
+// assistant/src/runtime/routes/migration-routes.ts), so a slow but healthy
+// export is never reported as failed while it is still uploading.
+const EXPORT_TIMEOUT_MS = 60 * 60 * 1000;
+// The daemon release that added `profile: "debug"`. An older daemon strips
+// the field and exports a normal teleport bundle, which carries the owner's
+// credentials. That must never reach the staff bucket.
+export const DEBUG_PROFILE_MIN_VERSION = "0.12.3";
+// Renew a cached guardian token that is about to lapse instead of starting
+// a long export on it.
+const TOKEN_EXPIRY_MARGIN_MS = 60 * 1000;
+
+function printHelp(): void {
+  console.log(`Usage: vellum debug-bundle [name]
+
+Send Vellum staff a debug bundle of a self-hosted assistant so they can
+inspect a copy of it. The bundle holds the assistant's workspace, its
+logs, and the gateway's own database. It never holds credentials.
+
+Arguments:
+  name    Assistant ID or unique display name. Defaults to the active
+          assistant (see 'vellum use'). Multi-word names need no quotes.
+
+Requirements:
+  - 'Allow Staff Access' is on for the assistant (Settings > Privacy).
+  - You are logged in ('vellum login'), which also registers the
+    assistant with the platform.
+  - The assistant runs version ${DEBUG_PROFILE_MIN_VERSION} or newer.
+  - The assistant is self-hosted. Vellum-hosted assistants need no bundle;
+    staff clone them directly.
+
+Side effects:
+  - Uploads the bundle to Vellum's debug-bundle storage, where it is
+    deleted after 7 days. Nothing on this machine changes.
+  - Records a 'debug bundle exported' entry in your account's audit history.
+  - Waits for the upload to finish (up to 60 minutes for a large workspace).
+
+Examples:
+  vellum debug-bundle
+  vellum debug-bundle my-assistant
+  vellum debug-bundle Support Bot
+`);
+}
+
+export async function debugBundle(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const entry = resolveTargetAssistant(parseAssistantTargetArg(args));
+  const reference = formatAssistantReference(entry);
+  if (entry.cloud === "vellum") {
+    console.error(
+      `${reference} is hosted by Vellum, so staff can clone it directly. No bundle is needed.`,
+    );
+    process.exit(1);
+  }
+
+  const platformToken = readPlatformToken();
+  if (!platformToken) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+  const platformAssistantId = entry.platformAssistantId?.trim();
+  if (!platformAssistantId) {
+    console.error(
+      `${reference} is not registered with the platform yet. Run 'vellum login' and retry.`,
+    );
+    process.exit(1);
+  }
+  const platformUrl = entry.platformBaseUrl?.trim() || getPlatformUrl();
+  const organizationId = entry.platformOrganizationId?.trim();
+
+  // Step 1: a guardian token for the daemon, and a check that the daemon
+  // knows the debug profile. This comes before the platform call so a
+  // daemon that would export credentials is refused before any URL exists.
+  let accessToken = await daemonAccessToken(entry, reference, false);
+  const { version } = await localRuntimeIdentity(entry, accessToken);
+  const comparison = compareVersions(version, DEBUG_PROFILE_MIN_VERSION);
+  if (comparison === null || comparison < 0) {
+    console.error(
+      `${reference} runs version ${version || "unknown"}, which cannot build a debug bundle. Update it to ${DEBUG_PROFILE_MIN_VERSION} or newer ('vellum upgrade') and retry.`,
+    );
+    process.exit(1);
+  }
+
+  // Step 2: the platform mints the upload URL, and refuses unless the
+  // owner's staff access grant is active.
+  const headers = organizationId
+    ? authHeadersForKnownOrganization(platformToken, organizationId)
+    : await authHeaders(platformToken, platformUrl);
+  const urlResponse = await loopbackSafeFetch(
+    `${platformUrl}/v1/assistants/${encodeURIComponent(platformAssistantId)}/debug-bundle-upload-url/`,
+    { method: "POST", headers },
+  );
+  if (urlResponse.status === 403) {
+    console.error(
+      "Staff access is off for this assistant. Turn on 'Allow Staff Access' in Settings > Privacy, then retry.",
+    );
+    process.exit(1);
+  }
+  if (!urlResponse.ok) {
+    const detail = await urlResponse.text().catch(() => "");
+    console.error(
+      `Error: Could not get an upload URL (${urlResponse.status}): ${detail || urlResponse.statusText}`,
+    );
+    process.exit(1);
+  }
+  const { url: uploadUrl } = (await urlResponse.json()) as { url: string };
+
+  // Step 3: the daemon builds and uploads the bundle.
+  let jobId: string;
+  try {
+    ({ jobId } = await localRuntimeExportToGcs(entry, accessToken, {
+      uploadUrl,
+      description: "debug bundle for Vellum staff",
+      profile: "debug",
+    }));
+  } catch (err) {
+    if (err instanceof MigrationInProgressError) {
+      console.error(
+        `Error: Another export is already in progress (job ${err.existingJobId}). Wait for it to finish, then retry.`,
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+  console.log(`Export started (job ${jobId})...`);
+
+  // Step 4: wait for the upload so the owner sees a real result. A large
+  // export can outlive the guardian token, so a 401 mid-poll re-leases one.
+  const terminal = await pollJobUntilDone({
+    label: "debug bundle export",
+    poll: () => localRuntimePollJobStatus(entry, accessToken, jobId),
+    timeoutMs: EXPORT_TIMEOUT_MS,
+    refreshOn401: async () => {
+      accessToken = await daemonAccessToken(entry, reference, true);
+    },
+  });
+  if (terminal.status === "failed") {
+    console.error(`Error: Export failed: ${terminal.error}`);
+    process.exit(1);
+  }
+  console.log(
+    "Debug bundle sent to Vellum. Staff can open it for the next 7 days.",
+  );
+}
+
+async function daemonAccessToken(
+  entry: {
+    assistantId: string;
+    runtimeUrl: string;
+    guardianBootstrapSecret?: string;
+  },
+  reference: string,
+  forceRefresh: boolean,
+): Promise<string> {
+  if (!forceRefresh) {
+    const cached = loadGuardianToken(entry.assistantId);
+    if (
+      cached &&
+      new Date(cached.accessTokenExpiresAt).getTime() - Date.now() >
+        TOKEN_EXPIRY_MARGIN_MS
+    ) {
+      return cached.accessToken;
+    }
+  }
+  try {
+    return (
+      await leaseGuardianToken(
+        entry.runtimeUrl,
+        entry.assistantId,
+        entry.guardianBootstrapSecret,
+      )
+    ).accessToken;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      console.error(`Error: Could not connect to ${reference}. Is it running?`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}

package/src/index.ts

@@ -31,6 +31,7 @@ import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
+import { debugBundle } from "./commands/debug-bundle";
 import { teleport } from "./commands/teleport";
 import { terminal } from "./commands/terminal";
 import { tunnel } from "./commands/tunnel";
@@ -45,6 +46,7 @@ import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
+  "debug-bundle": debugBundle,
   backup,
   clean,
   client,
@@ -125,6 +127,9 @@ function printHelp(): void {
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");
+  console.log(
+    "  debug-bundle  Send Vellum staff a debug bundle of a self-hosted assistant",
+  );
   console.log("  teleport Transfer assistant data between environments");
   console.log("  terminal Open a terminal into a managed assistant container");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");

package/src/lib/local-runtime-client.ts

@@ -116,12 +116,23 @@ async function throwIfInProgress(
 export async function localRuntimeExportToGcs(
   entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
   token: string,
-  params: { uploadUrl: string; description?: string },
+  params: {
+    uploadUrl: string;
+    description?: string;
+    /**
+     * `"debug"` builds a bundle for Vellum staff: no credentials, plus the
+     * gateway's database and logs. Omitted means a normal teleport bundle.
+     */
+    profile?: "migration" | "debug";
+  },
 ): Promise<{ jobId: string }> {
   const body: Record<string, unknown> = { upload_url: params.uploadUrl };
   if (params.description !== undefined) {
     body.description = params.description;
   }
+  if (params.profile !== undefined) {
+    body.profile = params.profile;
+  }
 
   const response = await loopbackSafeFetch(
     resolveRuntimeMigrationUrl(entry, "export-to-gcs"),

package/src/shared/provider-env-vars.ts

@@ -47,6 +47,7 @@ export const SEARCH_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   fastcrw: "FASTCRW_API_KEY",
   searxng: "SEARXNG_API_KEY",
   tinyfish: "TINYFISH_API_KEY",
+  exa: "EXA_API_KEY",
 };
 
 /**