@vellumai/assistant 0.6.4 → 0.6.5

package/src/__tests__/workspace-policy.test.ts

@@ -212,19 +212,7 @@ describe("isWorkspaceScopedInvocation", () => {
   // ── Network tools ──────────────────────────────────────────────────
 
   describe("network tools", () => {
-    const networkTools = [
-      "web_search",
-      "web_fetch",
-      "browser_navigate",
-      "browser_click",
-      "browser_type",
-      "browser_scroll",
-      "browser_screenshot",
-      "browser_close",
-      "browser_attach",
-      "browser_detach",
-      "network_request",
-    ];
+    const networkTools = ["web_search", "web_fetch", "network_request"];
 
     for (const tool of networkTools) {
       test(`${tool} is NOT workspace-scoped`, () => {

package/src/acp/client-handler.ts

@@ -412,12 +412,11 @@ function mapDecisionToOptionId(
     decision === "allow_10m" ||
     decision === "allow_conversation" ||
     decision === "always_allow" ||
-    decision === "always_allow_high_risk" ||
     decision === "temporary_override";
 
   if (isAllow) {
     // Prefer allow_always for persistent decisions, fallback to allow_once
-    if (decision === "always_allow" || decision === "always_allow_high_risk") {
+    if (decision === "always_allow") {
       const alwaysOpt = options.find((o) => o.kind === "allow_always");
       if (alwaysOpt) return alwaysOpt.optionId;
     }

package/src/agent/loop.ts

@@ -1,6 +1,11 @@
 import * as Sentry from "@sentry/node";
 
-import { estimateToolsTokens } from "../context/token-estimator.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import {
+  estimatePromptTokensRaw,
+  estimateToolsTokens,
+  getCalibrationProviderKey,
+} from "../context/token-estimator.js";
 import { truncateOversizedToolResults } from "../context/tool-result-truncation.js";
 import { getHookManager } from "../hooks/manager.js";
 import type {
@@ -15,7 +20,9 @@ import {
   applyStreamingSubstitution,
   applySubstitutions,
 } from "../tools/sensitive-output-placeholders.js";
+import { ProviderError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
+import { isRetryableNetworkError } from "../util/retry.js";
 
 const log = getLogger("agent-loop");
 
@@ -23,7 +30,7 @@ export interface AgentLoopConfig {
   maxTokens: number;
   maxInputTokens?: number; // context window size for tool result truncation
   thinking?: { enabled: boolean };
-  effort: "low" | "medium" | "high" | "max";
+  effort: "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
   toolChoice?:
     | { type: "auto" }
@@ -100,6 +107,13 @@ export type AgentEvent =
       providerDurationMs: number;
       rawRequest?: unknown;
       rawResponse?: unknown;
+      /**
+       * Pre-send token estimate for the same call. Used by the estimator
+       * calibrator to learn how off the heuristic is versus provider
+       * ground truth. Omitted only when estimation genuinely was not run
+       * for this call (e.g. legacy/stubbed code paths).
+       */
+      estimatedInputTokens?: number;
     };
 
 const DEFAULT_CONFIG: AgentLoopConfig = {
@@ -111,6 +125,42 @@ const DEFAULT_CONFIG: AgentLoopConfig = {
 const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
 const MAX_EMPTY_RESPONSE_RETRIES = 1;
 
+/**
+ * User-config HTTP status codes that should never page the on-call: billing
+ * exhaustion (402), invalid credentials (401), and forbidden/plan-gated (403).
+ * The user-facing error path already surfaces an actionable message (e.g.
+ * credits_exhausted); a Sentry issue adds noise without engineering signal.
+ */
+const USER_CONFIG_STATUS_CODES = new Set([401, 402, 403]);
+
+/**
+ * Whether an agent-loop error should be reported to Sentry. Suppresses:
+ *
+ *  - `ProviderError` carrying a user-config status code (401/402/403) — these
+ *    are bad API keys, exhausted billing, or plan gates, not engineering bugs.
+ *  - Retry-exhausted transient network errors (`retriesExhausted === true` +
+ *    still categorized as retryable network) — the retry loop already tried
+ *    its best; the user's network was flaky, not our code.
+ *
+ * Everything else (5xx with no retry-exhaustion tag, surprise errors, tool
+ * failures, etc.) still pages.
+ */
+export function shouldCaptureAgentLoopError(err: Error): boolean {
+  if (
+    err instanceof ProviderError &&
+    err.statusCode !== undefined &&
+    USER_CONFIG_STATUS_CODES.has(err.statusCode)
+  ) {
+    return false;
+  }
+  const exhausted = (err as Error & { retriesExhausted?: boolean })
+    .retriesExhausted;
+  if (exhausted === true && isRetryableNetworkError(err)) {
+    return false;
+  }
+  return true;
+}
+
 export interface ResolvedSystemPrompt {
   systemPrompt: string;
   maxTokens?: number;
@@ -204,8 +254,10 @@ export class AgentLoop {
     signal?: AbortSignal,
     requestId?: string,
     onCheckpoint?: (checkpoint: CheckpointInfo) => CheckpointDecision,
+    callSite?: LLMCallSite,
   ): Promise<Message[]> {
     const history = [...messages];
+    const initialHistoryLength = messages.length;
     let toolUseTurns = 0;
     let consecutiveErrorTurns = 0;
     let emptyResponseRetries = 0;
@@ -221,6 +273,11 @@ export class AgentLoop {
     while (true) {
       if (signal?.aborted) break;
 
+      rlog.info(
+        { turn: toolUseTurns, messageCount: history.length },
+        "Agent loop iteration start",
+      );
+
       let toolUseBlocks: Extract<ContentBlock, { type: "tool_use" }>[] = [];
 
       try {
@@ -235,25 +292,47 @@ export class AgentLoop {
           ? this.resolveSystemPrompt(history)
           : null;
         const turnSystemPrompt = resolved?.systemPrompt ?? this.systemPrompt;
-        const turnMaxTokens = resolved?.maxTokens ?? this.config.maxTokens;
         const turnModel = resolved?.model;
 
-        const providerConfig: Record<string, unknown> = {
-          max_tokens: turnMaxTokens,
-        };
-        if (turnModel) {
-          providerConfig.model = turnModel;
-        }
-        if (this.config.thinking?.enabled) {
-          providerConfig.thinking = { type: "adaptive" };
+        // Field precedence (highest wins):
+        //   1. Per-turn explicit (`resolved.maxTokens` / `resolved.model`)
+        //   2. Call-site resolved values (filled by
+        //      `RetryProvider.normalizeSendMessageOptions` from
+        //      `resolveCallSiteConfig(callSite, llm)`)
+        //   3. Conversation defaults (`this.config.*`, sourced from
+        //      `llm.default`)
+        //
+        // When `callSite` is present we deliberately leave
+        // `max_tokens`/`thinking`/`effort`/`speed` *unset* in `providerConfig`
+        // so the normalizer can fill them from the call-site resolution. The
+        // normalizer only writes these fields when they're undefined; if we
+        // pre-set them from `this.config` here, every per-call-site override
+        // for these knobs is silently ignored.
+        //
+        // `toolChoice` and `cacheTtl` are not part of the call-site schema, so
+        // they always come from `this.config` regardless of `callSite`.
+        const providerConfig: Record<string, unknown> = {};
+
+        if (resolved?.maxTokens !== undefined) {
+          providerConfig.max_tokens = resolved.maxTokens;
+        } else if (!callSite) {
+          providerConfig.max_tokens = this.config.maxTokens;
         }
 
-        if (this.config.effort) {
-          providerConfig.effort = this.config.effort;
+        if (turnModel) {
+          providerConfig.model = turnModel;
         }
 
-        if (this.config.speed && this.config.speed !== "standard") {
-          providerConfig.speed = this.config.speed;
+        if (!callSite) {
+          if (this.config.thinking?.enabled) {
+            providerConfig.thinking = { type: "adaptive" };
+          }
+          if (this.config.effort) {
+            providerConfig.effort = this.config.effort;
+          }
+          if (this.config.speed && this.config.speed !== "standard") {
+            providerConfig.speed = this.config.speed;
+          }
         }
 
         if (this.config.toolChoice) {
@@ -264,6 +343,17 @@ export class AgentLoop {
           providerConfig.cacheTtl = this.config.cacheTtl;
         }
 
+        // Per-call LLM call-site identifier. Surfaces on the per-call
+        // `config.callSite` so `RetryProvider.normalizeSendMessageOptions`
+        // can route through `resolveCallSiteConfig` against
+        // `llm.callSites.<id>` (falling back to `llm.default` when absent).
+        // User-initiated conversation turns default to `mainAgent` in the
+        // agent loop's caller; other invocation contexts (heartbeat, filing,
+        // analyze, etc.) pass their own `callSite`.
+        if (callSite) {
+          providerConfig.callSite = callSite;
+        }
+
         const preLlmResult = await getHookManager().trigger("pre-llm-call", {
           systemPrompt: turnSystemPrompt,
           messages: history,
@@ -292,6 +382,25 @@ export class AgentLoop {
         const providerStart = Date.now();
         lastLlmCallTime = providerStart;
 
+        // Compute the pre-send estimate against the full in-memory
+        // history — matching what upstream callers of
+        // `estimatePromptTokens` (preflight, mid-loop checkpoints, the
+        // window manager) see. We use the RAW estimate (before applying
+        // the existing correction) so the calibrator learns the true
+        // bias against provider ground truth instead of ratcheting a
+        // feedback loop against its own corrected output.
+        const toolTokenBudget =
+          currentTools.length > 0 ? estimateToolsTokens(currentTools) : 0;
+        const preSendEstimatedTokens = estimatePromptTokensRaw(
+          history,
+          turnSystemPrompt,
+          {
+            providerName: getCalibrationProviderKey(this.provider),
+            toolTokenBudget,
+          },
+        );
+        rlog.info({ turn: toolUseTurns }, "LLM call start");
+
         // Strip image contentBlocks from older tool results to prevent
         // screenshots from accumulating in the context window. The LLM
         // already saw each image on the turn it was captured; keeping
@@ -372,6 +481,7 @@ export class AgentLoop {
           providerDurationMs,
           rawRequest: response.rawRequest,
           rawResponse: response.rawResponse,
+          estimatedInputTokens: preSendEstimatedTokens,
         });
 
         void getHookManager().trigger("post-llm-call", {
@@ -407,17 +517,65 @@ export class AgentLoop {
             block.type === "tool_use",
         );
 
+        rlog.info(
+          {
+            turn: toolUseTurns,
+            stopReason: response.stopReason,
+            contentBlocks: response.content.length,
+            toolUseCount: toolUseBlocks.length,
+            durationMs: providerDurationMs,
+          },
+          "LLM call complete",
+        );
+
         // Detect empty responses: no user-visible text and no tool calls.
         // This can happen when the model fails to produce output after
         // receiving a large tool result. Retry once with a nudge before
         // the message is persisted.
+        //
+        // Only nudge when the model hasn't already delivered text to the user
+        // earlier in this tool-use chain. If a prior assistant turn in history
+        // contained visible text (e.g. the model said its piece before calling
+        // a side-effect tool like `remember`), an empty follow-up is the model
+        // correctly ending its turn — nudging would mislead it into thinking
+        // its earlier text didn't land and cause a verbatim re-send.
+        //
+        // Note: we check ANY prior assistant turn from this run()
+        // invocation, not just the most recent one. In multi-step tool-use
+        // chains (say-something → call-tool → call-another-tool → end),
+        // the "say-something" text lives on an earlier assistant turn while
+        // the most recent assistant turn is a pure tool_use with no text.
+        // Restricting the check to the most recent assistant turn would
+        // falsely nudge in that case and trigger a duplicate re-send of
+        // text the user already saw.
+        //
+        // Scope the scan to messages appended during this run() call only.
+        // Assistant text from prior conversation turns (earlier run()
+        // invocations passed in via `messages`) must NOT suppress the
+        // nudge — those turns completed long ago and have no bearing on
+        // whether the current tool-use chain has delivered text yet.
         const hasVisibleText = response.content.some(
           (block) => block.type === "text" && block.text.trim().length > 0,
         );
+        const priorAssistantHadVisibleText = (() => {
+          for (let i = history.length - 1; i >= initialHistoryLength; i--) {
+            const msg = history[i];
+            if (msg.role !== "assistant") continue;
+            const hasText = msg.content.some(
+              (block) =>
+                block.type === "text" &&
+                typeof (block as { text?: unknown }).text === "string" &&
+                (block as { text: string }).text.trim().length > 0,
+            );
+            if (hasText) return true;
+          }
+          return false;
+        })();
         if (
           !hasVisibleText &&
           toolUseBlocks.length === 0 &&
           toolUseTurns > 0 &&
+          !priorAssistantHadVisibleText &&
           emptyResponseRetries < MAX_EMPTY_RESPONSE_RETRIES
         ) {
           emptyResponseRetries++;
@@ -437,7 +595,12 @@ export class AgentLoop {
           continue;
         }
 
-        if (!hasVisibleText && toolUseBlocks.length === 0 && toolUseTurns > 0) {
+        if (
+          !hasVisibleText &&
+          toolUseBlocks.length === 0 &&
+          toolUseTurns > 0 &&
+          !priorAssistantHadVisibleText
+        ) {
           rlog.error(
             { turn: toolUseTurns, retries: emptyResponseRetries },
             "Model returned empty response after tool results — retries exhausted",
@@ -479,6 +642,15 @@ export class AgentLoop {
         // Execute all tools concurrently for reduced latency.
         // Race against the abort signal so cancellation isn't blocked by
         // stuck tools (e.g. a hung browser navigation).
+        const toolExecStart = Date.now();
+        rlog.info(
+          {
+            turn: toolUseTurns,
+            toolNames: toolUseBlocks.map((t) => t.name),
+          },
+          "Tool execution start",
+        );
+
         const toolExecutionPromise = Promise.all(
           toolUseBlocks.map(async (toolUse) => {
             const result = await this.toolExecutor!(
@@ -522,6 +694,15 @@ export class AgentLoop {
           toolResults = await toolExecutionPromise;
         }
 
+        rlog.info(
+          {
+            turn: toolUseTurns,
+            toolCount: toolResults.length,
+            durationMs: Date.now() - toolExecStart,
+          },
+          "Tool execution complete",
+        );
+
         // Merge sensitive output bindings from tool results into the
         // per-run substitution map. Bindings carry placeholder->value pairs
         // that are resolved in streamed text deltas and final message text.
@@ -653,12 +834,23 @@ export class AgentLoop {
           { err, turn: toolUseTurns, messageCount: history.length },
           "Agent loop error during turn processing",
         );
-        Sentry.captureException(err);
+        if (shouldCaptureAgentLoopError(err)) {
+          Sentry.captureException(err);
+        }
         onEvent({ type: "error", error: err });
         break;
       }
     }
 
+    rlog.info(
+      {
+        turns: toolUseTurns,
+        finalMessageCount: history.length,
+        aborted: signal?.aborted ?? false,
+      },
+      "Agent loop exited",
+    );
+
     return history;
   }
 }

package/src/avatar/resvg-lazy.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for resvg-lazy and the writeTraitsAndRenderAvatar fallback it feeds.
+ *
+ * Covers the graceful-degradation path when the native @resvg/resvg-js binding
+ * is missing (e.g. bun install skipped the platform-specific optional
+ * dependency). The lazy loader must warn once and report unavailability, and
+ * writeTraitsAndRenderAvatar must return `native_unavailable` so the HTTP
+ * layer can respond 503 instead of 500.
+ *
+ * Bun's `mock.module` evaluates factories eagerly on re-registration, which
+ * makes it awkward to flip a module between "throws" and "returns fake
+ * export" across tests in the same file. We instead install a single
+ * throwing mock at module scope for the require-path test, and use the
+ * `__setResvgCacheForTests` / `__resetResvgCacheForTests` hooks to drive the
+ * rest of the cases deterministically.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+type LogCall = { bindings: unknown; msg: string };
+const warnCalls: LogCall[] = [];
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () => ({
+    warn: (bindings: unknown, msg: string) => {
+      warnCalls.push({ bindings, msg });
+    },
+    info: () => {},
+    error: () => {},
+    debug: () => {},
+    trace: () => {},
+    fatal: () => {},
+  }),
+}));
+
+mock.module("../util/platform.js", () => ({
+  AVATAR_IMAGE_FILENAME: "avatar-image.png",
+  getAvatarDir: () => "/tmp/vellum-test-avatar-never-written",
+}));
+
+// Install a throwing @resvg/resvg-js mock at module scope. Bun only calls
+// this factory the first time the module is required within the test worker;
+// later `require` calls return whatever was produced by that first call (or
+// throw, if the factory threw). That's exactly what we want for the
+// "require fails" test below.
+mock.module("@resvg/resvg-js", () => {
+  throw new Error("Cannot require module @resvg/resvg-js-darwin-x64");
+});
+
+describe("resvg-lazy — require failure path", () => {
+  beforeEach(async () => {
+    warnCalls.length = 0;
+    const { __resetResvgCacheForTests } = await import("./resvg-lazy.js");
+    __resetResvgCacheForTests();
+  });
+
+  test("real require failure triggers warn log with platform context", async () => {
+    const { isResvgAvailable } = await import("./resvg-lazy.js");
+
+    // Call twice — caching must prevent a duplicate warn.
+    expect(isResvgAvailable()).toBe(false);
+    expect(isResvgAvailable()).toBe(false);
+
+    expect(warnCalls.length).toBe(1);
+    const call = warnCalls[0]!;
+    const bindings = call.bindings as Record<string, unknown>;
+    expect(bindings.platform).toBe(process.platform);
+    expect(bindings.arch).toBe(process.arch);
+    expect(String(bindings.module)).toContain("@resvg/resvg-js-");
+    expect(bindings.err).toBeInstanceOf(Error);
+    expect(call.msg).toContain("@resvg/resvg-js");
+  });
+});
+
+describe("resvg-lazy — API shape when unavailable", () => {
+  beforeEach(async () => {
+    warnCalls.length = 0;
+    const { __setResvgCacheForTests } = await import("./resvg-lazy.js");
+    __setResvgCacheForTests({
+      available: false,
+      error: new Error("Cannot require module @resvg/resvg-js-darwin-x64"),
+    });
+  });
+
+  test("isResvgAvailable returns false", async () => {
+    const { isResvgAvailable } = await import("./resvg-lazy.js");
+    expect(isResvgAvailable()).toBe(false);
+  });
+
+  test("getResvg throws the underlying error", async () => {
+    const { getResvg } = await import("./resvg-lazy.js");
+    expect(() => getResvg()).toThrow(
+      /Cannot require module @resvg\/resvg-js-darwin-x64/,
+    );
+  });
+});
+
+describe("writeTraitsAndRenderAvatar — native module missing", () => {
+  beforeEach(async () => {
+    warnCalls.length = 0;
+    const { __setResvgCacheForTests } = await import("./resvg-lazy.js");
+    __setResvgCacheForTests({
+      available: false,
+      error: new Error("Cannot require module @resvg/resvg-js-darwin-x64"),
+    });
+  });
+
+  test("returns native_unavailable without attempting disk writes", async () => {
+    const { writeTraitsAndRenderAvatar } = await import("./traits-png-sync.js");
+
+    const result = writeTraitsAndRenderAvatar({
+      bodyShape: "blob",
+      eyeStyle: "curious",
+      color: "green",
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return; // narrow for TypeScript
+    expect(result.reason).toBe("native_unavailable");
+    expect(result.message).toContain("@resvg/resvg-js");
+  });
+
+  test("returns invalid_traits (not native_unavailable) when traits are bad", async () => {
+    const { writeTraitsAndRenderAvatar } = await import("./traits-png-sync.js");
+
+    // Empty traits object fails the shape check before we ever consult resvg.
+    const result = writeTraitsAndRenderAvatar({
+      bodyShape: "",
+      eyeStyle: "",
+      color: "",
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe("invalid_traits");
+  });
+});

package/src/avatar/resvg-lazy.ts

@@ -1,21 +1,94 @@
 import type { Resvg as ResvgType } from "@resvg/resvg-js";
 
-let ResvgClass: typeof ResvgType | undefined;
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("resvg-lazy");
+
+type ResvgLoadResult =
+  | { available: true; Resvg: typeof ResvgType }
+  | { available: false; error: Error };
+
+let cached: ResvgLoadResult | undefined;
+
+function loadResvg(): ResvgLoadResult {
+  try {
+    // Inline require is necessary here: @resvg/resvg-js loads a platform-specific
+    // native .node addon at import time. A top-level import would crash the daemon
+    // on startup inside bun --compile binaries where native addons are unavailable.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require("@resvg/resvg-js") as typeof import("@resvg/resvg-js");
+    return { available: true, Resvg: mod.Resvg };
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    // Log once at warn level (not error) — the daemon should keep running and
+    // callers should fall back to a non-native path (ASCII only, or a 503 at
+    // the HTTP layer). Emitting at error level would page Sentry on every
+    // install that skipped the platform-specific optional dependency.
+    log.warn(
+      {
+        err: error,
+        platform: process.platform,
+        arch: process.arch,
+        module: `@resvg/resvg-js-${process.platform}-${process.arch}`,
+      },
+      "Failed to load @resvg/resvg-js native module — avatar PNG rendering will be unavailable. " +
+        "The platform-specific optional dependency is likely missing.",
+    );
+    return { available: false, error };
+  }
+}
+
+function getLoadResult(): ResvgLoadResult {
+  if (!cached) {
+    cached = loadResvg();
+  }
+  return cached;
+}
+
+/**
+ * Returns `true` if the native @resvg/resvg-js binding loaded successfully on
+ * first access. Callers should check this before calling `getResvg()` and fall
+ * back to a non-native path (e.g. ASCII-only rendering, or a 503 at the HTTP
+ * layer) when it is `false`.
+ *
+ * Loading is attempted lazily on first access and the result is cached, so
+ * calling this multiple times is cheap and does not re-emit warnings.
+ */
+export function isResvgAvailable(): boolean {
+  return getLoadResult().available;
+}
 
 /**
  * Returns the Resvg constructor, loading the native module on first call.
  * Defers the native-addon require so the daemon can start even when the
  * platform-specific binary is unavailable (e.g. inside a bun --compile
  * single-file executable).
+ *
+ * Throws if the native module could not be loaded. Callers that need to
+ * degrade gracefully should check `isResvgAvailable()` first.
  */
 export function getResvg(): typeof ResvgType {
-  if (!ResvgClass) {
-    // Inline require is necessary here: @resvg/resvg-js loads a platform-specific
-    // native .node addon at import time. A top-level import would crash the daemon
-    // on startup inside bun --compile binaries where native addons are unavailable.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const mod = require("@resvg/resvg-js") as typeof import("@resvg/resvg-js");
-    ResvgClass = mod.Resvg;
+  const result = getLoadResult();
+  if (!result.available) {
+    throw result.error;
   }
-  return ResvgClass;
+  return result.Resvg;
+}
+
+/**
+ * Test-only hook to reset the cached load result between test cases. Do not
+ * call from production code.
+ */
+export function __resetResvgCacheForTests(): void {
+  cached = undefined;
+}
+
+/**
+ * Test-only hook to force the cached load result to a specific state without
+ * exercising the real `require`. Useful for asserting the unavailable path
+ * without depending on Bun's module-mock behavior (which re-imports the real
+ * module after the factory throws once).
+ */
+export function __setResvgCacheForTests(result: ResvgLoadResult): void {
+  cached = result;
 }

package/src/avatar/traits-png-sync.ts

@@ -7,6 +7,7 @@ import { AVATAR_IMAGE_FILENAME, getAvatarDir } from "../util/platform.js";
 import { renderCharacterAscii } from "./ascii-renderer.js";
 import { getCharacterComponents } from "./character-components.js";
 import { renderCharacterPng } from "./png-renderer.js";
+import { isResvgAvailable } from "./resvg-lazy.js";
 
 const log = getLogger("traits-png-sync");
 
@@ -20,7 +21,7 @@ export type TraitsSyncResult =
   | { ok: true; asciiWritten: boolean }
   | {
       ok: false;
-      reason: "invalid_traits" | "render_error";
+      reason: "invalid_traits" | "render_error" | "native_unavailable";
       message: string;
     };
 
@@ -144,6 +145,25 @@ export function writeTraitsAndRenderAvatar(
     };
   }
 
+  // Short-circuit before touching disk when the native rasterizer is missing.
+  // Both PNG and ASCII rendering route through @resvg/resvg-js, so without it
+  // we cannot produce either artifact. Callers translate this into a 503 so
+  // the HTTP route returns an actionable status rather than a 500.
+  if (!isResvgAvailable()) {
+    log.warn(
+      { traits },
+      "Skipping avatar render — native @resvg/resvg-js binding is unavailable",
+    );
+    return {
+      ok: false,
+      reason: "native_unavailable",
+      message:
+        "Avatar PNG rendering is unavailable on this platform because the " +
+        "@resvg/resvg-js native binding failed to load. Reinstall dependencies " +
+        "to pull the platform-specific optional package.",
+    };
+  }
+
   const avatarDir = getAvatarDir();
   const traitsPath = join(avatarDir, "character-traits.json");