@vellumai/assistant 0.11.6 → 0.11.7-staging.2

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

@@ -0,0 +1,29 @@
+/**
+ * @vellumai/avatar-manifest: the single source of truth for the on-disk
+ * avatar layout of an assistant workspace (`<workspace>/data/avatar`) and
+ * how its files resolve to an avatar.
+ *
+ * The daemon owns the files (it writes the manifest and sidecars); hosts
+ * such as the desktop app read them directly so a sleeping assistant still
+ * has an avatar in the chooser. Both go through the parsing and legacy
+ * derivation here so they cannot disagree. Leaf package: node builtins only.
+ */
+export {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  AVATAR_TRAITS_FILENAME,
+  resolveAvatarDir,
+} from "./layout.js";
+export {
+  deriveAvatarFromLegacyFiles,
+  parseAvatarManifest,
+} from "./manifest.js";
+export type {
+  AvatarImageMeta,
+  AvatarKind,
+  AvatarSource,
+  AvatarState,
+  CharacterTraits,
+} from "./manifest.js";
+export { readWorkspaceAvatar } from "./read.js";
+export type { WorkspaceAvatar } from "./read.js";

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

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+
+/** Path segments of the avatar directory below the workspace directory. */
+const AVATAR_DIR_SEGMENTS: readonly string[] = ["data", "avatar"];
+
+/** Avatar state manifest. */
+export const AVATAR_MANIFEST_FILENAME = "avatar.json";
+
+/** Legacy sidecar holding the persisted character traits. */
+export const AVATAR_TRAITS_FILENAME = "character-traits.json";
+
+/** The avatar PNG (uploaded, or rendered from the character traits). */
+export const AVATAR_IMAGE_FILENAME = "avatar-image.png";
+
+/** The avatar directory for a workspace (`<workspace>/data/avatar`). */
+export function resolveAvatarDir(workspaceDir: string): string {
+  return join(workspaceDir, ...AVATAR_DIR_SEGMENTS);
+}

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

@@ -0,0 +1,156 @@
+export type AvatarKind = "character" | "image" | "none";
+export type AvatarSource = "builder" | "upload" | "ai";
+
+export interface CharacterTraits {
+  bodyShape: string;
+  eyeStyle: string;
+  color: string;
+}
+
+export interface AvatarImageMeta {
+  updatedAt: string;
+  etag: string;
+}
+
+/** The persisted manifest (`avatar.json`). */
+export interface AvatarState {
+  kind: AvatarKind;
+  traits: CharacterTraits | null;
+  source: AvatarSource | null;
+  image: AvatarImageMeta | null;
+}
+
+const AVATAR_KINDS: ReadonlySet<string> = new Set<AvatarKind>([
+  "character",
+  "image",
+  "none",
+]);
+
+const AVATAR_SOURCES: ReadonlySet<string> = new Set<AvatarSource>([
+  "builder",
+  "upload",
+  "ai",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
+
+/** Longest string any manifest field may carry (trait ids, etags, timestamps). */
+export const AVATAR_FIELD_MAX_LENGTH = 256;
+
+function isBoundedString(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= AVATAR_FIELD_MAX_LENGTH
+  );
+}
+
+/** Narrows an unknown value to valid CharacterTraits (presence and length only). */
+function isValidCharacterTraits(value: unknown): value is CharacterTraits {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.bodyShape) &&
+    isBoundedString(value.eyeStyle) &&
+    isBoundedString(value.color)
+  );
+}
+
+/** Narrows an unknown value to valid AvatarImageMeta (presence and length only). */
+function isValidAvatarImageMeta(value: unknown): value is AvatarImageMeta {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.updatedAt) &&
+    isBoundedString(value.etag)
+  );
+}
+
+/**
+ * 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
+ * missing or malformed, so callers fall back to legacy derivation instead
+ * of surfacing an avatar with null traits/image. An unknown `source` and any
+ * payload irrelevant to the kind normalize to `null` rather than passing
+ * through, so the result always satisfies the wire shape.
+ */
+export function parseAvatarManifest(value: unknown): AvatarState | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.kind !== "string" || !AVATAR_KINDS.has(value.kind)) {
+    return null;
+  }
+  const kind = value.kind as AvatarKind;
+  const source =
+    typeof value.source === "string" && AVATAR_SOURCES.has(value.source)
+      ? (value.source as AvatarSource)
+      : null;
+  if (kind === "character") {
+    if (!isValidCharacterTraits(value.traits)) {
+      return null;
+    }
+    return { kind, traits: value.traits, source, image: null };
+  }
+  if (kind === "image") {
+    if (!isValidAvatarImageMeta(value.image)) {
+      return null;
+    }
+    return { kind, traits: null, source, image: value.image };
+  }
+  return { kind, traits: null, source, image: null };
+}
+
+type LegacyAvatarDerivation =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image" }
+  | { kind: "none" };
+
+/**
+ * Derives the avatar from the legacy sidecar files when there is no usable
+ * manifest. Traits-first: valid traits win even when the PNG also exists,
+ * because the builder writes the rendered PNG after the traits file, so
+ * mtimes cannot tell a built character from an uploaded image.
+ */
+export function deriveAvatarFromLegacyFiles(input: {
+  traitsJson: unknown;
+  hasImage: boolean;
+}): LegacyAvatarDerivation {
+  if (isValidCharacterTraits(input.traitsJson)) {
+    return { kind: "character", traits: input.traitsJson };
+  }
+  return input.hasImage ? { kind: "image" } : { kind: "none" };
+}
+
+type ResolvedAvatar =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image"; image: AvatarImageMeta | null }
+  | { kind: "none" };
+
+/**
+ * Resolves the avatar from the parsed avatar files: the manifest when it is
+ * valid, otherwise the legacy derivation. `image` carries the manifest's
+ * metadata when the manifest decided, and is null for a legacy PNG.
+ */
+export function resolveAvatarFromFiles(input: {
+  manifestJson: unknown;
+  traitsJson: unknown;
+  hasImage: boolean;
+}): ResolvedAvatar {
+  const manifest = parseAvatarManifest(input.manifestJson);
+  if (manifest) {
+    switch (manifest.kind) {
+      case "character":
+        return {
+          kind: "character",
+          traits: manifest.traits as CharacterTraits,
+        };
+      case "image":
+        return { kind: "image", image: manifest.image };
+      case "none":
+        return { kind: "none" };
+    }
+  }
+  const legacy = deriveAvatarFromLegacyFiles(input);
+  return legacy.kind === "image" ? { kind: "image", image: null } : legacy;
+}

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

@@ -0,0 +1,109 @@
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+
+import {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  AVATAR_TRAITS_FILENAME,
+  resolveAvatarDir,
+} from "./layout.js";
+import { type CharacterTraits, resolveAvatarFromFiles } from "./manifest.js";
+
+export type WorkspaceAvatar =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image"; imagePath: string }
+  | { kind: "none" };
+
+/** Largest sidecar a host parses; a bigger one counts as absent. */
+export const AVATAR_SIDECAR_MAX_BYTES = 64 * 1024;
+
+function isWithin(root: string, target: string): boolean {
+  return target === root || target.startsWith(root + sep);
+}
+
+/**
+ * Sidecars are read through one validated descriptor: the parent must
+ * resolve beneath the real workspace (a symlinked avatar dir is rejected),
+ * the file must be a regular file at or under the cap, and the open uses
+ * O_NOFOLLOW with a post-open recheck so a swap between check and read
+ * cannot substitute another file. Anything else counts as absent.
+ */
+function readJsonFile(workspaceDir: string, filePath: string): unknown {
+  let fd: number | undefined;
+  try {
+    const realRoot = realpathSync(workspaceDir);
+    const realDir = realpathSync(dirname(filePath));
+    if (!isWithin(realRoot, realDir)) {
+      return undefined;
+    }
+    const realPath = join(realDir, basename(filePath));
+    const linkStats = lstatSync(realPath);
+    if (!linkStats.isFile() || linkStats.size > AVATAR_SIDECAR_MAX_BYTES) {
+      return undefined;
+    }
+    fd = openSync(realPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const stats = fstatSync(fd);
+    if (
+      !stats.isFile() ||
+      stats.dev !== linkStats.dev ||
+      stats.ino !== linkStats.ino ||
+      stats.size > AVATAR_SIDECAR_MAX_BYTES
+    ) {
+      return undefined;
+    }
+    const reopened = realpathSync(filePath);
+    if (!isWithin(realRoot, reopened)) {
+      return undefined;
+    }
+    const reopenedStats = lstatSync(reopened);
+    if (
+      !reopenedStats.isFile() ||
+      reopenedStats.dev !== stats.dev ||
+      reopenedStats.ino !== stats.ino
+    ) {
+      return undefined;
+    }
+    const text = readFileSync(fd, "utf-8");
+    if (Buffer.byteLength(text) > AVATAR_SIDECAR_MAX_BYTES) {
+      return undefined;
+    }
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) {
+      closeSync(fd);
+    }
+  }
+}
+
+/**
+ * Reads the avatar of a workspace directly off disk. Unreadable or corrupt
+ * files count as absent. For an image avatar the caller reads the PNG at
+ * `imagePath` itself, applying its own size policy; the file may be missing.
+ */
+export function readWorkspaceAvatar(workspaceDir: string): WorkspaceAvatar {
+  const avatarDir = resolveAvatarDir(workspaceDir);
+  const imagePath = join(avatarDir, AVATAR_IMAGE_FILENAME);
+  const resolved = resolveAvatarFromFiles({
+    manifestJson: readJsonFile(
+      workspaceDir,
+      join(avatarDir, AVATAR_MANIFEST_FILENAME),
+    ),
+    traitsJson: readJsonFile(
+      workspaceDir,
+      join(avatarDir, AVATAR_TRAITS_FILENAME),
+    ),
+    hasImage: existsSync(imagePath),
+  });
+  return resolved.kind === "image" ? { kind: "image", imagePath } : resolved;
+}

package/node_modules/@vellumai/avatar-manifest/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/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/ingress.test.ts

@@ -6,8 +6,10 @@ import {
   normalizePublicBaseUrl,
   parseRecordedAssistantId,
   parseTunnelRecord,
+  selectRestartTunnelRecord,
   trimmedNonEmptyString,
   TUNNEL_PROVIDERS,
+  type TunnelRecord,
   velayHostForPlatformHost,
 } from "../ingress.js";
 import {
@@ -221,6 +223,41 @@ describe("parseTunnelRecord", () => {
   });
 });
 
+describe("selectRestartTunnelRecord", () => {
+  const PAIRING: TunnelRecord = {
+    provider: "tailscale",
+    publicBaseUrl: "https://assistant-1.example.ts.net",
+  };
+  const LAST: TunnelRecord = {
+    provider: "ngrok",
+    publicBaseUrl: "https://assistant-1.ngrok.app",
+  };
+
+  test("prefers the pairing tunnel over the last one that ran", () => {
+    // The pairing tunnel deliberately left the older public record beside it,
+    // so naming that one would point at an ingress nobody is using.
+    expect(
+      selectRestartTunnelRecord({ lastTunnel: LAST, pairingTunnel: PAIRING }),
+    ).toEqual(PAIRING);
+  });
+
+  test("falls back to the last tunnel and to null", () => {
+    expect(selectRestartTunnelRecord({ lastTunnel: LAST })).toEqual(LAST);
+    for (const ingress of [undefined, null, {}, "nonsense", 42]) {
+      expect(selectRestartTunnelRecord(ingress)).toBeNull();
+    }
+  });
+
+  test("skips a malformed pairing record for a usable last one", () => {
+    expect(
+      selectRestartTunnelRecord({
+        lastTunnel: LAST,
+        pairingTunnel: { provider: "wireguard", publicBaseUrl: "nope" },
+      }),
+    ).toEqual(LAST);
+  });
+});
+
 describe("trimmedNonEmptyString", () => {
   test("trims and rejects blank or non-string values", () => {
     expect(trimmedNonEmptyString(" assistant-1 ")).toBe("assistant-1");