@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/platform/sync-avatar.ts

@@ -0,0 +1,209 @@
+/**
+ * Sync the avatar raster to the platform Assistant record.
+ *
+ * Every avatar publish (routes and the fs watcher) and daemon startup enqueue
+ * a sync through the shared platform PATCH queue. The current avatar state is
+ * read when the request runs, so rapid changes collapse into one PATCH
+ * carrying the newest raster. The dedup key comes from the raster file itself,
+ * not the manifest, so a raster rewritten in place (fs watcher path) still
+ * syncs. The last synced key is persisted outside the workspace repo at
+ * `<protected dir>/platform-sync/avatar.json` so a daemon restart does not
+ * re-upload an unchanged raster and the record never dirties the workspace.
+ * A synced key older than `AVATAR_SYNC_KEY_TTL_MS` does not dedup, whether
+ * seeded from disk or set in-process, and the queue re-enqueues itself when
+ * the key expires, so an avatar lost server-side while id and base URL are
+ * unchanged is re-pushed within a week even by a daemon that never restarts
+ * (API-key auth cannot read the record to verify it).
+ * `avatar_base64: null` is sent only when the avatar is actually removed; a
+ * non-none avatar whose raster is missing (image PNG gone, character
+ * re-render unavailable) is skipped so the platform keeps the last synced
+ * copy.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { readAvatarState } from "../avatar/avatar-manifest.js";
+import {
+  ensureAvatarRasterPath,
+  readContainedAvatarRaster,
+} from "../avatar/ensure-raster.js";
+import { getResvg, isResvgAvailable } from "../avatar/resvg-lazy.js";
+import { detectMediaType } from "../tools/shared/filesystem/image-read.js";
+import { getLogger } from "../util/logger.js";
+import { getProtectedDir } from "../util/platform.js";
+import {
+  createPlatformPatchQueue,
+  type PatchPayload,
+  type PlatformPatchQueue,
+  type SyncedKey,
+} from "./platform-patch-queue.js";
+
+const log = getLogger("sync-avatar");
+
+/** Largest raster sent as-is; bigger ones are downscaled first. */
+const MAX_AVATAR_UPLOAD_BYTES = 256 * 1024;
+const DOWNSCALE_PX = 128;
+const NONE_KEY = "none";
+/** Raster formats resvg decodes inside an `<image>`; anything else renders blank. */
+const RESVG_DECODABLE_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+]);
+/** Only bytes that sniff as a raster image are ever uploaded. */
+const UPLOADABLE_TYPES: ReadonlySet<string> = new Set([
+  ...RESVG_DECODABLE_TYPES,
+  "image/webp",
+]);
+const SYNC_STATE_SUBPATH = ["platform-sync", "avatar.json"];
+export const AVATAR_SYNC_KEY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+let queue: PlatformPatchQueue<void> | null = null;
+
+/** Recreates the queue so the next sync re-seeds its dedup key from disk. */
+export function _resetSyncAvatarStateForTests(): void {
+  queue?.dispose();
+  queue = null;
+}
+
+/**
+ * Enqueue a best-effort push of the current avatar raster to the platform.
+ * No-op when the platform client cannot be created or no assistant id is
+ * configured, or when the raster's etag matches the last successful sync.
+ */
+export function syncAvatarToPlatform(): void {
+  queue ??= createPlatformPatchQueue({
+    log,
+    label: "avatar",
+    buildPayload,
+    loadSyncedKey: readPersistedKey,
+    saveSyncedKey: persistKey,
+    maxAgeMs: AVATAR_SYNC_KEY_TTL_MS,
+  });
+  queue.enqueue();
+}
+
+function syncStatePath(): string {
+  return join(getProtectedDir(), ...SYNC_STATE_SUBPATH);
+}
+
+/** Returns the persisted key, or null when missing or malformed. */
+function readPersistedKey(): SyncedKey | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(syncStatePath(), "utf-8"));
+    const { key, syncedAt } = (parsed ?? {}) as {
+      key?: unknown;
+      syncedAt?: unknown;
+    };
+    if (typeof key !== "string" || typeof syncedAt !== "number") {
+      return null;
+    }
+    return { key, syncedAt };
+  } catch {
+    return null;
+  }
+}
+
+function persistKey(synced: SyncedKey): void {
+  try {
+    const path = syncStatePath();
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmpPath, JSON.stringify(synced));
+    renameSync(tmpPath, path);
+  } catch (err) {
+    log.warn({ err }, "Failed to persist avatar sync state");
+  }
+}
+
+async function buildPayload(): Promise<PatchPayload | undefined> {
+  const state = readAvatarState();
+  if (state.kind === "none") {
+    return { key: NONE_KEY, body: { avatar_base64: null } };
+  }
+  const path = await ensureAvatarRasterPath(state);
+  if (!path) {
+    log.warn({ kind: state.kind }, "Avatar raster missing; skipping sync");
+    return undefined;
+  }
+  const bytes = readRaster(path);
+  if (!bytes) {
+    return undefined;
+  }
+  // Keyed on content so a same-size, same-mtime rewrite still re-syncs.
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  return {
+    key: `${state.kind}:${digest}`,
+    body: async () => {
+      const encoded = encodeForUpload(bytes);
+      if (encoded === undefined) {
+        log.warn(
+          { bytes: bytes.length, cap: MAX_AVATAR_UPLOAD_BYTES },
+          "Avatar raster exceeds upload cap and could not be downscaled; skipping sync",
+        );
+        return undefined;
+      }
+      return { avatar_base64: encoded };
+    },
+  };
+}
+
+/**
+ * Reads the raster through the fd-validated, avatar-dir-contained path and
+ * refuses anything that does not sniff as an image, so a symlinked or
+ * swapped `avatar-image.png` never ships host bytes to the platform.
+ */
+function readRaster(path: string): Buffer | undefined {
+  const bytes = readContainedAvatarRaster(path);
+  if (!bytes) {
+    log.warn(
+      { path },
+      "Avatar raster unreadable or not contained; skipping sync",
+    );
+    return undefined;
+  }
+  const mediaType = detectMediaType(bytes);
+  if (mediaType === null || !UPLOADABLE_TYPES.has(mediaType)) {
+    log.warn({ mediaType }, "Avatar raster is not an image; skipping sync");
+    return undefined;
+  }
+  return bytes;
+}
+
+function downscaleRaster(bytes: Buffer): Buffer | null {
+  if (!isResvgAvailable()) {
+    return null;
+  }
+  const mediaType = detectMediaType(bytes);
+  if (mediaType === null || !RESVG_DECODABLE_TYPES.has(mediaType)) {
+    log.warn(
+      { mediaType },
+      "Avatar raster format is not decodable by resvg; skipping downscale",
+    );
+    return null;
+  }
+  const href = `data:${mediaType};base64,${bytes.toString("base64")}`;
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${DOWNSCALE_PX}" height="${DOWNSCALE_PX}" viewBox="0 0 ${DOWNSCALE_PX} ${DOWNSCALE_PX}">` +
+    `<image width="${DOWNSCALE_PX}" height="${DOWNSCALE_PX}" preserveAspectRatio="xMidYMid meet" href="${href}" xlink:href="${href}"/></svg>`;
+  const Resvg = getResvg();
+  const resvg = new Resvg(svg, {
+    fitTo: { mode: "width", value: DOWNSCALE_PX },
+  });
+  return Buffer.from(resvg.render().asPng());
+}
+
+/** Returns the base64 payload, or undefined when the raster cannot fit the cap. */
+function encodeForUpload(bytes: Buffer): string | undefined {
+  let upload: Buffer | null = bytes;
+  if (upload.length > MAX_AVATAR_UPLOAD_BYTES) {
+    upload = downscaleRaster(upload);
+  }
+  if (!upload || upload.length > MAX_AVATAR_UPLOAD_BYTES) {
+    return undefined;
+  }
+  return upload.toString("base64");
+}

package/src/platform/sync-identity.test.ts

@@ -0,0 +1,75 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let mockClient: {
+  baseUrl: string;
+  platformAssistantId: string;
+  fetch: (path: string, init: RequestInit) => Promise<Response>;
+} | null;
+
+mock.module("./client.js", () => ({
+  VellumPlatformClient: { create: async () => mockClient },
+}));
+
+import { syncIdentityNameToPlatform } from "./sync-identity.js";
+
+interface Patch {
+  path: string;
+  body: { name: string };
+}
+
+let patches: Patch[];
+
+function makeClient(assistantId = "asst-1") {
+  return {
+    baseUrl: "https://platform.a",
+    platformAssistantId: assistantId,
+    fetch: async (path: string, init: RequestInit) => {
+      patches.push({ path, body: JSON.parse(init.body as string) });
+      return new Response("{}", { status: 200 });
+    },
+  };
+}
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+// The module owns one queue, so names are unique per test to avoid dedup
+// across tests. Queue semantics are covered by platform-patch-queue.test.ts.
+describe("syncIdentityNameToPlatform", () => {
+  beforeEach(() => {
+    patches = [];
+    mockClient = makeClient();
+  });
+
+  test("PATCHes the name and dedups an unchanged name", async () => {
+    syncIdentityNameToPlatform("Ada");
+    await settle();
+    syncIdentityNameToPlatform("Ada");
+    await settle();
+
+    expect(patches).toEqual([
+      { path: "/v1/assistants/asst-1/", body: { name: "Ada" } },
+    ]);
+  });
+
+  test("rapid changes collapse into one PATCH carrying the newest name", async () => {
+    syncIdentityNameToPlatform("Bea");
+    syncIdentityNameToPlatform("Cy");
+    syncIdentityNameToPlatform("Dee");
+    await settle();
+
+    expect(patches.map((p) => p.body.name)).toEqual(["Dee"]);
+  });
+
+  test("empty names and a missing client are no-ops", async () => {
+    syncIdentityNameToPlatform("");
+    mockClient = null;
+    syncIdentityNameToPlatform("Eve");
+    await settle();
+
+    expect(patches).toHaveLength(0);
+  });
+});

package/src/platform/sync-identity.ts

@@ -2,16 +2,11 @@
  * Sync assistant identity fields to the platform Assistant record.
  *
  * When IDENTITY.md changes on disk the daemon broadcasts an
- * `identity_changed` event to connected clients.  This module hooks into
- * that same change signal and PATCHes the platform `Assistant` record so
- * the name (and, in future, other fields) stays in sync.
- *
- * Requests are serialized so that rapid name changes (A → B) never race:
- * only the most recently requested name is sent, and a stale in-flight
- * response cannot overwrite a newer value.
- *
- * The sync is best-effort and fire-and-forget — network failures are
- * logged but never surface to callers.
+ * `identity_changed` event to connected clients. This module hooks into that
+ * same change signal and PATCHes the platform `Assistant` record through the
+ * shared platform PATCH queue so the name stays in sync: rapid changes
+ * collapse to the newest name, and an unchanged name is not re-sent to the
+ * same platform destination.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -19,49 +14,27 @@ import { existsSync, readFileSync } from "node:fs";
 import { parseIdentityFields } from "../daemon/handlers/identity.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspacePromptPath } from "../util/platform.js";
-import { VellumPlatformClient } from "./client.js";
+import { createPlatformPatchQueue } from "./platform-patch-queue.js";
 
 const log = getLogger("sync-identity");
 
-/** Track the last successfully synced name (used inside doSync to skip redundant PATCHes). */
-let lastSyncedName: string | null = null;
-
-/** Track the last requested name (used for dedup at enqueue time). */
-let lastRequestedName: string | null = null;
-
-/**
- * Monotonically increasing sequence number.  Each call to
- * `syncIdentityNameToPlatform` bumps this; after a PATCH completes we
- * only update `lastSyncedName` when `seq` still matches, guaranteeing
- * the newest name always wins.
- */
-let seq = 0;
-
-/** Chain promise that serializes in-flight PATCH requests. */
-let pending: Promise<void> = Promise.resolve();
+const queue = createPlatformPatchQueue<string>({
+  log,
+  label: "assistant name",
+  buildPayload: (name) => ({
+    key: name,
+    body: { name },
+  }),
+});
 
 /**
  * Push the current assistant name to the platform `Assistant` record.
- *
- * No-op when:
- * - The platform client cannot be created (not platform-hosted / missing creds).
- * - No assistant ID is configured.
- * - The name is empty or unchanged since the last request.
+ * Empty names are ignored.
  */
 export function syncIdentityNameToPlatform(name: string): void {
-  if (!name || name === lastRequestedName) {
-    return;
+  if (name) {
+    queue.enqueue(name);
   }
-
-  lastRequestedName = name;
-
-  const mySeq = ++seq;
-
-  pending = pending
-    .then(() => doSync(name, mySeq))
-    .catch(() => {
-      // swallowed — doSync already logs internally
-    });
 }
 
 /**
@@ -83,69 +56,3 @@ export function syncWorkspaceIdentityToPlatform(): void {
     log.error({ err }, "Failed to sync identity to platform at startup");
   }
 }
-
-async function doSync(name: string, requestSeq: number): Promise<void> {
-  try {
-    // A newer call has already been enqueued — skip this stale request.
-    if (requestSeq !== seq) {
-      return;
-    }
-
-    // Re-check after awaiting the previous request in the chain.
-    if (name === lastSyncedName) {
-      return;
-    }
-
-    const client = await VellumPlatformClient.create();
-    if (!client) {
-      clearRequestedIfLatest(requestSeq);
-      return;
-    }
-
-    const assistantId = client.platformAssistantId;
-    if (!assistantId) {
-      clearRequestedIfLatest(requestSeq);
-      return;
-    }
-
-    const resp = await client.fetch(
-      `/v1/assistants/${encodeURIComponent(assistantId)}/`,
-      {
-        method: "PATCH",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name }),
-        signal: AbortSignal.timeout(15_000),
-      },
-    );
-
-    if (resp.ok) {
-      // Only update cache if no newer request has been enqueued since we
-      // started this PATCH — prevents a slow response from overwriting a
-      // fresher value.
-      if (requestSeq === seq) {
-        lastSyncedName = name;
-      }
-      log.info({ name, assistantId }, "Synced assistant name to platform");
-    } else {
-      clearRequestedIfLatest(requestSeq);
-      const text = await resp.text();
-      log.warn(
-        { status: resp.status, body: text, assistantId },
-        "Failed to sync assistant name to platform",
-      );
-    }
-  } catch (err) {
-    clearRequestedIfLatest(requestSeq);
-    log.warn({ err }, "Error syncing assistant name to platform");
-  }
-}
-
-/**
- * Reset `lastRequestedName` when the latest request failed, so that the
- * next call with the same name is allowed through instead of being deduped.
- */
-function clearRequestedIfLatest(requestSeq: number): void {
-  if (requestSeq === seq) {
-    lastRequestedName = lastSyncedName;
-  }
-}

package/src/plugin-api/model-profiles.test.ts

@@ -61,8 +61,8 @@ describe("getModelProfiles", () => {
 
     const result = listProfiles();
     // The code-catalog defaults are always present; the two workspace
-    // entries shadow their catalog counterparts, and the remaining catalog
-    // default sorts after the explicit order.
+    // entries shadow their catalog counterparts, and managed backups remain
+    // internal fallback routes rather than picker options.
     expect(result.map((p) => p.key)).toEqual([
       "balanced",
       "quality-optimized",

package/src/plugin-api/model-profiles.ts

@@ -1,15 +1,15 @@
-import { getEffectiveProfilesForProvider } from "../config/default-profile-catalog.js";
+import { getUserSelectableProfilesForProvider } from "../config/default-profile-catalog.js";
 import { getConfig } from "../config/loader.js";
 import { isDispatchableProfile } from "../config/profile-dispatchability.js";
 import { orderProfileKeys } from "../config/profile-order.js";
 import type { ModelProfileInfo } from "./types.js";
 
 /**
- * List the workspace inference profiles a plugin can route to, in the order the
- * `/model` picker presents them (`llm.profileOrder` first, then the rest
- * alphabetically). Metadata-only entries without a provider, model, or mix are
- * not routing targets, so plugins never see them. Disabled profiles are
- * included and flagged via
+ * List the workspace inference profiles a plugin can route to, in the order a
+ * user-facing model picker presents them (`llm.profileOrder` first, then the
+ * rest alphabetically). Managed backup routes are internal and omitted.
+ * Metadata-only entries without a provider, model, or mix are not routing
+ * targets, so plugins never see them. Disabled profiles are included and flagged via
  * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
  * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
  * routing target (it resolves to one constituent per conversation).
@@ -20,7 +20,7 @@ import type { ModelProfileInfo } from "./types.js";
 export function getModelProfiles(): ModelProfileInfo[] {
   const { llm } = getConfig();
   const { activeProfile } = llm;
-  const profiles = getEffectiveProfilesForProvider(
+  const profiles = getUserSelectableProfilesForProvider(
     llm.profiles,
     llm.defaultProvider ?? null,
   );

package/src/plugin-api/transcription-session.ts

@@ -35,5 +35,5 @@ import type { StreamingTranscriber } from "../stt/types.js";
 export async function openTranscriptionSession(): Promise<StreamingTranscriber | null> {
   const { resolveStreamingTranscriber } =
     await import("../providers/speech-to-text/resolve.js");
-  return resolveStreamingTranscriber();
+  return resolveStreamingTranscriber({ role: "dictation" });
 }

package/src/plugins/defaults/compaction/window-manager.ts

@@ -84,6 +84,10 @@ export interface ContextWindowResult {
   summaryModel: string;
   summaryCallSite?: LLMCallSite;
   summaryOverrideProfile?: string | null;
+  /** See {@link CompactionRunResult.summaryActualProvider}. */
+  summaryActualProvider?: string;
+  /** See {@link CompactionRunResult.summaryActualInferenceProfile}. */
+  summaryActualInferenceProfile?: string;
   summaryCacheCreationInputTokens?: number;
   summaryCacheReadInputTokens?: number;
   summaryRawResponses?: unknown[];

package/src/plugins/defaults/image-recovery/recover.ts

@@ -66,8 +66,8 @@ export const UNSENDABLE_IMAGE_NOTE =
  * bytes untouched. An unsendable image that can be resized is rewritten to
  * its resized form (downscaled when oversized, upscaled to the minimum floor
  * when undersized); one that cannot be resized on this host (resize is a
- * no-op, e.g. `sips` is absent off macOS or the format is unsupported) is
- * replaced with a text note.
+ * no-op because the encoder cannot decode the format) is replaced with a text
+ * note.
  *
  * Shared by the in-memory recovery transform and the durable persist pass so
  * both apply the identical rule. Persisting the resized form is what lets a