@vellumai/cli 0.11.8 → 0.11.9-dev.202609041316.d96b917

package/README.md

@@ -54,18 +54,17 @@ 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`, `docker`, `vellum`, `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`, `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.
 - **`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
@@ -87,7 +86,7 @@ vellum hatch --remote docker
 vellum hatch --name my-assistant --remote docker
 ```
 
-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.
+To self-host on a cloud VM (AWS, GCP, or any other provider), SSH into the machine and run `vellum hatch` or `vellum hatch --remote docker` from inside it. The CLI does not provision cloud instances for you.
 
 ### `terminal`
 

package/knip.json

@@ -2,7 +2,6 @@
   "entry": [
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
-    "src/adapters/openclaw-http-server.ts",
     "src/lib/version-compat.ts",
     "src/lib/platform-releases.ts",
     "src/lib/cli-error.ts"

package/node_modules/@vellumai/avatar-manifest/package.json

@@ -5,7 +5,8 @@
   "license": "MIT",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./accent": "./src/accent.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  dominantAccentHex,
+  isAvatarAccentHex,
+  normalizeAvatarAccentHex,
+} from "../accent.js";
+
+/** An RGBA block from `[r, g, b, a, count]` runs. */
+function pixels(...runs: [number, number, number, number, number][]) {
+  const out: number[] = [];
+  for (const [r, g, b, a, count] of runs) {
+    for (let i = 0; i < count; i += 1) {
+      out.push(r, g, b, a);
+    }
+  }
+  return new Uint8ClampedArray(out);
+}
+
+function channels(hex: string): [number, number, number] {
+  const n = parseInt(hex.slice(1), 16);
+  return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+
+function saturation(hex: string): number {
+  const ch = channels(hex).map((c) => c / 255);
+  const max = Math.max(...ch);
+  const min = Math.min(...ch);
+  const l = (max + min) / 2;
+  return max === min ? 0 : (max - min) / (1 - Math.abs(2 * l - 1));
+}
+
+describe("isAvatarAccentHex / normalizeAvatarAccentHex", () => {
+  test("accepts #rrggbb in either case and canonicalizes to lowercase", () => {
+    expect(isAvatarAccentHex("#E9642F")).toBe(true);
+    expect(normalizeAvatarAccentHex("  #E9642F ")).toBe("#e9642f");
+  });
+
+  test.each([
+    ["short form", "#abc"],
+    ["no hash", "e9642f"],
+    ["alpha channel", "#e9642fff"],
+    ["not a string", 0xe9642f],
+    ["empty", ""],
+  ])("rejects %s", (_label, value) => {
+    expect(isAvatarAccentHex(value)).toBe(false);
+    expect(normalizeAvatarAccentHex(value)).toBeNull();
+  });
+});
+
+describe("dominantAccentHex", () => {
+  test("picks the coloured mark over the white ground it sits on", () => {
+    // Nine in ten pixels are white; the accent is still the red.
+    const hex = dominantAccentHex(
+      pixels([255, 255, 255, 255, 90], [200, 30, 30, 255, 10]),
+    );
+    expect(hex).toBe("#c81e1e");
+  });
+
+  test("picks the coloured mark over a black ground", () => {
+    expect(
+      dominantAccentHex(pixels([0, 0, 0, 255, 90], [40, 120, 200, 255, 10])),
+    ).toBe("#2878c8");
+  });
+
+  test("prefers the more prevalent of two accents", () => {
+    expect(
+      dominantAccentHex(
+        pixels([200, 30, 30, 255, 30], [40, 120, 200, 255, 50]),
+      ),
+    ).toBe("#2878c8");
+  });
+
+  test("averages a gradient of one hue rather than splitting it", () => {
+    // Three reds close together are one bin; a lone saturated blue is not
+    // more prevalent than the three of them together.
+    const hex = dominantAccentHex(
+      pixels(
+        [200, 30, 30, 255, 10],
+        [210, 40, 35, 255, 10],
+        [190, 25, 28, 255, 10],
+        [40, 120, 200, 255, 12],
+      ),
+    );
+    const [r, , b] = channels(hex!);
+    expect(r).toBeGreaterThan(b);
+  });
+
+  test("keeps a gray image gray instead of inventing a hue", () => {
+    const hex = dominantAccentHex(
+      pixels([120, 120, 120, 255, 80], [122, 121, 119, 255, 20]),
+    );
+    expect(saturation(hex!)).toBeLessThan(0.05);
+  });
+
+  test("a stray colourful pixel does not outrank a gray image", () => {
+    const hex = dominantAccentHex(
+      pixels([128, 128, 128, 255, 98], [255, 0, 0, 255, 2]),
+    );
+    expect(saturation(hex!)).toBeLessThan(0.05);
+  });
+
+  test("skips transparent pixels: a cutout's ground is not its colour", () => {
+    const cutout = dominantAccentHex(
+      pixels([0, 0, 0, 0, 90], [40, 120, 200, 255, 10]),
+    );
+    expect(cutout).toBe(dominantAccentHex(pixels([40, 120, 200, 255, 10])));
+  });
+
+  test("returns null when nothing is opaque enough to count", () => {
+    expect(dominantAccentHex(pixels([12, 34, 56, 0, 40]))).toBeNull();
+    expect(dominantAccentHex(new Uint8ClampedArray())).toBeNull();
+  });
+
+  test("returns a canonical lowercase #rrggbb", () => {
+    expect(dominantAccentHex(pixels([233, 100, 47, 255, 4]))).toBe("#e9642f");
+  });
+});

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

@@ -16,7 +16,13 @@ describe("parseAvatarManifest", () => {
   test("accepts a character manifest", () => {
     expect(
       parseAvatarManifest({ kind: "character", traits, source: "builder" }),
-    ).toEqual({ kind: "character", traits, source: "builder", image: null });
+    ).toEqual({
+      kind: "character",
+      traits,
+      source: "builder",
+      image: null,
+      accent: null,
+    });
   });
 
   test("accepts an image manifest", () => {
@@ -25,6 +31,58 @@ describe("parseAvatarManifest", () => {
       traits: null,
       source: null,
       image,
+      accent: null,
+    });
+  });
+
+  test("keeps a well-formed accent on a character or image manifest", () => {
+    const accent = { hex: "#e9642f", source: "custom" as const };
+    expect(parseAvatarManifest({ kind: "image", image, accent })).toEqual({
+      kind: "image",
+      traits: null,
+      source: null,
+      image,
+      accent,
+    });
+    expect(parseAvatarManifest({ kind: "character", traits, accent })).toEqual({
+      kind: "character",
+      traits,
+      source: null,
+      image: null,
+      accent,
+    });
+  });
+
+  test.each([
+    ["a short hex", { hex: "#abc", source: "derived" }],
+    ["an unknown source", { hex: "#e9642f", source: "guess" }],
+    ["a missing source", { hex: "#e9642f" }],
+    ["a non-object", "#e9642f"],
+  ])(
+    "normalizes %s accent to null without failing the manifest",
+    (_label, accent) => {
+      expect(parseAvatarManifest({ kind: "image", image, accent })).toEqual({
+        kind: "image",
+        traits: null,
+        source: null,
+        image,
+        accent: null,
+      });
+    },
+  );
+
+  test("drops an accent from a none manifest", () => {
+    expect(
+      parseAvatarManifest({
+        kind: "none",
+        accent: { hex: "#e9642f", source: "custom" },
+      }),
+    ).toEqual({
+      kind: "none",
+      traits: null,
+      source: null,
+      image: null,
+      accent: null,
     });
   });
 
@@ -34,6 +92,7 @@ describe("parseAvatarManifest", () => {
       traits: null,
       source: null,
       image: null,
+      accent: null,
     });
   });
 
@@ -61,27 +120,47 @@ describe("parseAvatarManifest", () => {
   test("normalizes an unknown source to null", () => {
     expect(
       parseAvatarManifest({ kind: "image", image, source: "unknown" }),
-    ).toEqual({ kind: "image", traits: null, source: null, image });
+    ).toEqual({
+      kind: "image",
+      traits: null,
+      source: null,
+      image,
+      accent: null,
+    });
     expect(parseAvatarManifest({ kind: "none", source: 7 })).toEqual({
       kind: "none",
       traits: null,
       source: null,
       image: null,
+      accent: null,
     });
   });
 
   test("drops payload irrelevant to the kind", () => {
     expect(
       parseAvatarManifest({ kind: "image", image, traits: { bodyShape: 1 } }),
-    ).toEqual({ kind: "image", traits: null, source: null, image });
+    ).toEqual({
+      kind: "image",
+      traits: null,
+      source: null,
+      image,
+      accent: null,
+    });
     expect(
       parseAvatarManifest({ kind: "character", traits, image: "stale" }),
-    ).toEqual({ kind: "character", traits, source: null, image: null });
+    ).toEqual({
+      kind: "character",
+      traits,
+      source: null,
+      image: null,
+      accent: null,
+    });
     expect(parseAvatarManifest({ kind: "none", traits, image })).toEqual({
       kind: "none",
       traits: null,
       source: null,
       image: null,
+      accent: null,
     });
   });
 

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

@@ -0,0 +1,150 @@
+/**
+ * The avatar accent: the one colour every surface that tints itself to the
+ * assistant paints with.
+ *
+ * A character avatar's accent is its palette colour. An uploaded image has no
+ * colour as data, so one is read out of its pixels here. Pure pixel math with
+ * no decoder: the daemon feeds it a raster decoded by sharp and the web feeds
+ * it a canvas, and because both go through this one function they cannot
+ * disagree about what colour an image is.
+ */
+
+/** `#rrggbb` only: the one form CSS, the native hex parsers, and the colour picker all agree on. */
+const ACCENT_HEX_PATTERN = /^#[0-9a-f]{6}$/i;
+
+/** Whether `value` is a `#rrggbb` string. */
+export function isAvatarAccentHex(value: unknown): value is string {
+  return typeof value === "string" && ACCENT_HEX_PATTERN.test(value);
+}
+
+/**
+ * Canonical form of an accent hex (`#rrggbb`, lowercase), or null when the
+ * input is not one. Surrounding whitespace is tolerated because the value can
+ * arrive from a text field.
+ */
+export function normalizeAvatarAccentHex(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return ACCENT_HEX_PATTERN.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+
+/** Pixels below this alpha are skipped: a cutout's transparent ground is not its colour. */
+const MIN_ALPHA = 128;
+
+/** Hue is bucketed this finely, so a gradient of one hue lands in one bin. */
+const HUE_BINS = 24;
+/** Chromatic bins are split by lightness this many ways, so a colour and its shadow stay apart. */
+const LIGHT_BANDS = 3;
+/** Below this saturation a pixel is counted as gray, bucketed by lightness alone. */
+const GRAY_SATURATION = 0.15;
+/** Gray bins by lightness. */
+const GRAY_BANDS = 5;
+
+interface Bin {
+  count: number;
+  r: number;
+  g: number;
+  b: number;
+  s: number;
+  l: number;
+}
+
+function rgbToHsl(
+  r: number,
+  g: number,
+  b: number,
+): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) {
+    return { h: 0, s: 0, l };
+  }
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h: number;
+  if (max === rn) {
+    h = ((gn - bn) / d) % 6;
+  } else if (max === gn) {
+    h = (bn - rn) / d + 2;
+  } else {
+    h = (rn - gn) / d + 4;
+  }
+  h /= 6;
+  return { h: h < 0 ? h + 1 : h, s, l };
+}
+
+function toHex(r: number, g: number, b: number): string {
+  const ch = (v: number) => Math.max(0, Math.min(255, Math.round(v)));
+  return `#${((1 << 24) | (ch(r) << 16) | (ch(g) << 8) | ch(b)).toString(16).slice(1)}`;
+}
+
+/**
+ * How much a bin's colour deserves to be the accent, per pixel in it.
+ *
+ * Population alone picks the background: most uploads are a subject on white
+ * or black. Saturation and mid lightness weight the bin instead, so a red mark
+ * on a white ground reads as red while an all-gray photo still reads as gray,
+ * because with nothing colourful to beat, the gray bin's small weight wins.
+ */
+function salience(s: number, l: number): number {
+  return (0.1 + 0.9 * s) * Math.max(0.1, 1 - Math.abs(l - 0.5) * 1.6);
+}
+
+/**
+ * The most prevalent accent colour in a block of RGBA pixels, as `#rrggbb`, or
+ * null when no pixel is opaque enough to count.
+ *
+ * Pixels are bucketed by hue and lightness (grays by lightness alone), each
+ * bucket is scored by population times how much it looks like an accent
+ * (saturated, mid-toned), and the winner's mean colour is the answer. The
+ * mean rather than the bucket centre, so a brand's exact orange comes back
+ * as that orange and not the nearest of twenty-four hues.
+ */
+export function dominantAccentHex(pixels: ArrayLike<number>): string | null {
+  const bins = new Map<number, Bin>();
+  for (let i = 0; i + 3 < pixels.length; i += 4) {
+    if (pixels[i + 3]! < MIN_ALPHA) {
+      continue;
+    }
+    const r = pixels[i]!;
+    const g = pixels[i + 1]!;
+    const b = pixels[i + 2]!;
+    const { h, s, l } = rgbToHsl(r, g, b);
+    const key =
+      s < GRAY_SATURATION
+        ? -1 - Math.min(GRAY_BANDS - 1, Math.floor(l * GRAY_BANDS))
+        : Math.min(HUE_BINS - 1, Math.floor(h * HUE_BINS)) * LIGHT_BANDS +
+          Math.min(LIGHT_BANDS - 1, Math.floor(l * LIGHT_BANDS));
+    let bin = bins.get(key);
+    if (!bin) {
+      bin = { count: 0, r: 0, g: 0, b: 0, s: 0, l: 0 };
+      bins.set(key, bin);
+    }
+    bin.count += 1;
+    bin.r += r;
+    bin.g += g;
+    bin.b += b;
+    bin.s += s;
+    bin.l += l;
+  }
+
+  let best: Bin | null = null;
+  let bestScore = -1;
+  for (const bin of bins.values()) {
+    const score = bin.count * salience(bin.s / bin.count, bin.l / bin.count);
+    if (score > bestScore) {
+      best = bin;
+      bestScore = score;
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  return toHex(best.r / best.count, best.g / best.count, best.b / best.count);
+}

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

@@ -14,11 +14,18 @@ export {
   AVATAR_TRAITS_FILENAME,
   resolveAvatarDir,
 } from "./layout.js";
+export {
+  dominantAccentHex,
+  isAvatarAccentHex,
+  normalizeAvatarAccentHex,
+} from "./accent.js";
 export {
   deriveAvatarFromLegacyFiles,
   parseAvatarManifest,
 } from "./manifest.js";
 export type {
+  AvatarAccent,
+  AvatarAccentSource,
   AvatarImageMeta,
   AvatarKind,
   AvatarSource,

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

@@ -1,3 +1,5 @@
+import { isAvatarAccentHex } from "./accent.js";
+
 export type AvatarKind = "character" | "image" | "none";
 export type AvatarSource = "builder" | "upload" | "ai";
 
@@ -12,12 +14,27 @@ export interface AvatarImageMeta {
   etag: string;
 }
 
+/**
+ * Where an accent came from. `palette`: a character's chosen colour.
+ * `derived`: read out of an uploaded image's pixels. `custom`: set by the
+ * user over an image. Only the last is worth offering a reset from.
+ */
+export type AvatarAccentSource = "palette" | "derived" | "custom";
+
+/** The colour every avatar-tinted surface paints with, as `#rrggbb`. */
+export interface AvatarAccent {
+  hex: string;
+  source: AvatarAccentSource;
+}
+
 /** The persisted manifest (`avatar.json`). */
 export interface AvatarState {
   kind: AvatarKind;
   traits: CharacterTraits | null;
   source: AvatarSource | null;
   image: AvatarImageMeta | null;
+  /** Null for `none`, and for an image whose colour could not be read. */
+  accent: AvatarAccent | null;
 }
 
 const AVATAR_KINDS: ReadonlySet<string> = new Set<AvatarKind>([
@@ -32,6 +49,12 @@ const AVATAR_SOURCES: ReadonlySet<string> = new Set<AvatarSource>([
   "ai",
 ]);
 
+const AVATAR_ACCENT_SOURCES: ReadonlySet<string> = new Set<AvatarAccentSource>([
+  "palette",
+  "derived",
+  "custom",
+]);
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object";
 }
@@ -66,6 +89,23 @@ function isValidAvatarImageMeta(value: unknown): value is AvatarImageMeta {
   );
 }
 
+/**
+ * An accent is optional on the wire and in the file: manifests written before
+ * accents existed carry none, and an unreadable image has none. Anything not
+ * a well-formed accent normalizes to null rather than failing the manifest.
+ */
+function parseAvatarAccent(value: unknown): AvatarAccent | null {
+  if (
+    !isRecord(value) ||
+    !isAvatarAccentHex(value.hex) ||
+    typeof value.source !== "string" ||
+    !AVATAR_ACCENT_SOURCES.has(value.source)
+  ) {
+    return null;
+  }
+  return { hex: value.hex, source: value.source as AvatarAccentSource };
+}
+
 /**
  * Validates a parsed `avatar.json`. Returns `null` for a non-object, an
  * invalid or missing `kind`, or a valid `kind` whose per-kind payload is
@@ -90,15 +130,27 @@ export function parseAvatarManifest(value: unknown): AvatarState | null {
     if (!isValidCharacterTraits(value.traits)) {
       return null;
     }
-    return { kind, traits: value.traits, source, image: null };
+    return {
+      kind,
+      traits: value.traits,
+      source,
+      image: null,
+      accent: parseAvatarAccent(value.accent),
+    };
   }
   if (kind === "image") {
     if (!isValidAvatarImageMeta(value.image)) {
       return null;
     }
-    return { kind, traits: null, source, image: value.image };
+    return {
+      kind,
+      traits: null,
+      source,
+      image: value.image,
+      accent: parseAvatarAccent(value.accent),
+    };
   }
-  return { kind, traits: null, source, image: null };
+  return { kind, traits: null, source, image: null, accent: null };
 }
 
 type LegacyAvatarDerivation =

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/package.json

@@ -5,7 +5,8 @@
   "license": "MIT",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./accent": "./src/accent.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",