@vellumai/assistant 0.8.3 → 0.8.5

package/src/tools/system/request-permission.ts

@@ -1,5 +1,4 @@
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { registerTool } from "../registry.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -57,13 +56,10 @@ class RequestSystemPermissionTool implements Tool {
     "Use when a tool fails with a permission/access error (e.g. 'Operation not permitted', 'EACCES', sandbox denial). " +
     "Do not explain how to open System Settings manually - this tool handles it with a clickable button.";
   category = "system";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.High;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           permission_type: {
@@ -78,9 +74,7 @@ class RequestSystemPermissionTool implements Tool {
           },
         },
         required: ["permission_type", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/terminal/safe-env.ts

@@ -61,12 +61,13 @@ export const SAFE_ENV_VARS = [
 ] as const;
 
 export const KATA_SAFE_ENV_VARS = [
-  "LD_LIBRARY_PATH",
   "VELLUM_APT_DATA_ROOT",
   "VELLUM_APT_DATA_SUITE",
   "VELLUM_APT_DATA_MIRROR",
 ] as const;
 
+export const KATA_INJECTED_ENV_VARS = ["LD_LIBRARY_PATH"] as const;
+
 const KATA_APT_DATA_ROOT = "/data/system";
 
 function kataAptPaths(dataRoot: string): string[] {
@@ -132,7 +133,7 @@ export function buildSanitizedEnv(): Record<string, string> {
     env.VELLUM_APT_DATA_ROOT = kataAptDataRoot;
     env.PATH = appendUniquePathEntries(env.PATH, kataAptPaths(kataAptDataRoot));
     env.LD_LIBRARY_PATH = appendUniquePathEntries(
-      env.LD_LIBRARY_PATH,
+      undefined,
       kataAptLibraryPaths(kataAptDataRoot),
     );
   }

package/src/tools/terminal/shell.ts

@@ -4,7 +4,6 @@ import { spawn } from "node:child_process";
 import { getConfig } from "../../config/loader.js";
 import { isCesShellLockdownEnabled } from "../../credential-execution/feature-gates.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
@@ -49,13 +48,10 @@ class ShellTool implements Tool {
   name = "bash";
   description = "Execute a shell command on the local machine";
   category = "terminal";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.Medium;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           command: {
@@ -91,9 +87,7 @@ class ShellTool implements Tool {
           },
         },
         required: ["command", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/tool-approval-handler.ts

@@ -334,9 +334,19 @@ export class ToolApprovalHandler {
       return { allowed: false, result: { content: msg, isError: true } };
     }
 
-    // Gate tools not active for the current turn
-    if (context.allowedToolNames && !context.allowedToolNames.has(name)) {
-      const msg = `Tool "${name}" is not currently active. Load the skill that provides this tool first.`;
+    // Look up the tool before the allowedToolNames gate so a name no skill
+    // provides surfaces as "Unknown tool" (with the real list) instead of
+    // the misleading "load the skill" hint.
+    const tool = getTool(name);
+    if (!tool) {
+      const allowedToolNames = context.allowedToolNames;
+      const available = getAllTools()
+        .filter((t) => t.executionMode !== "proxy" || context.proxyToolResolver)
+        .map((t) => t.name)
+        .filter((n) => !allowedToolNames || allowedToolNames.has(n))
+        .sort()
+        .join(", ");
+      const msg = `Unknown tool: ${name}. Available tools: ${available}`;
       const durationMs = Date.now() - startTime;
       emitLifecycleEvent({
         type: "error",
@@ -356,15 +366,12 @@ export class ToolApprovalHandler {
       return { allowed: false, result: { content: msg, isError: true } };
     }
 
-    // Resolve the tool from the registry
-    const tool = getTool(name);
-    if (!tool) {
-      const available = getAllTools()
-        .filter((t) => t.executionMode !== "proxy" || context.proxyToolResolver)
-        .map((t) => t.name)
-        .sort()
-        .join(", ");
-      const msg = `Unknown tool: ${name}. Available tools: ${available}`;
+    // Gate tools not active for the current turn
+    if (context.allowedToolNames && !context.allowedToolNames.has(name)) {
+      const loadHint = tool.ownerSkillId
+        ? `Load the "${tool.ownerSkillId}" skill that provides this tool first.`
+        : `Load the skill that provides this tool first.`;
+      const msg = `Tool "${name}" is not currently active. ${loadHint}`;
       const durationMs = Date.now() - startTime;
       emitLifecycleEvent({
         type: "error",

package/src/tools/tool-defaults.ts

@@ -0,0 +1,94 @@
+/**
+ * Single source of truth for the defaults applied when a `ToolDefinition`
+ * omits one of the normally-required fields, plus the `finalizeTool`
+ * helper that lifts a `ToolDefinition` into a `LoadedTool`.
+ *
+ * Plugins, external loaders, and any other registration boundary that
+ * accepts loose `ToolDefinition` objects from authors must run them
+ * through `finalizeTool` before handing the result to a `registerXxxTools`
+ * call. The registry types make this a hard rule: every registered tool
+ * is a `LoadedTool` (`Required<ToolDefinition> & { name }`).
+ */
+
+import type {
+  LoadedTool,
+  RiskLevel,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "./types.js";
+
+/**
+ * Default values applied by `finalizeTool` when the author omits a field.
+ *
+ * - `description` defaults to empty — the model sees the tool name only
+ *   for un-documented tools, which is the correct minimal-info signal.
+ * - `defaultRiskLevel` defaults to `medium` — the safe middle band that
+ *   forces explicit approval for risky calls without spamming approval
+ *   prompts on no-op tools.
+ * - `input_schema` defaults to an empty closed object — the model is
+ *   allowed to call the tool with no arguments, and unknown arguments
+ *   are rejected at the JSON-schema layer.
+ * - `executionTarget` defaults to `sandbox` — author-supplied tool code
+ *   runs in the assistant container by default; opt in to `host` when
+ *   the tool proxies work to the connected client.
+ *
+ * `execute` has no constant default because the default closure needs to
+ * close over the tool's name to produce a useful error message; see
+ * `finalizeTool` below.
+ */
+export const TOOL_DEFAULTS = Object.freeze({
+  description: "",
+  defaultRiskLevel: "medium" as RiskLevel,
+  input_schema: Object.freeze({
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+  }) as object,
+  executionTarget: "sandbox" as const,
+});
+
+/**
+ * Fill the four normally-required `ToolDefinition` fields with documented
+ * defaults when the author omitted them, attach the registration-time
+ * `name`, and return a `LoadedTool` that is safe to hand to a
+ * `registerXxxTools` call.
+ *
+ * The default `execute` returns an error result so the model sees a clear
+ * "this tool isn't wired up" signal at call time. The owning loader still
+ * registers the tool cleanly — a broken individual tool must never block
+ * the registration batch.
+ */
+export function finalizeTool(
+  tool: ToolDefinition,
+  name: string,
+): LoadedTool {
+  const description =
+    typeof tool.description === "string"
+      ? tool.description
+      : TOOL_DEFAULTS.description;
+  const defaultRiskLevel =
+    typeof tool.defaultRiskLevel === "string"
+      ? tool.defaultRiskLevel
+      : TOOL_DEFAULTS.defaultRiskLevel;
+  const input_schema =
+    tool.input_schema !== null && typeof tool.input_schema === "object"
+      ? tool.input_schema
+      : TOOL_DEFAULTS.input_schema;
+  const execute =
+    typeof tool.execute === "function"
+      ? tool.execute
+      : async (): Promise<ToolExecutionResult> => ({
+          content: `tool ${name} has no execute implementation`,
+          isError: true,
+        });
+  const executionTarget = tool.executionTarget ?? TOOL_DEFAULTS.executionTarget;
+  return {
+    ...tool,
+    name,
+    description,
+    defaultRiskLevel,
+    input_schema,
+    executionTarget,
+    execute,
+  };
+}

package/src/tools/types.ts

@@ -5,7 +5,6 @@ import type {
   ProxyApprovalCallback,
   RiskLevel,
   SensitiveOutputBinding,
-  ToolDefinition,
   ToolExecutionErrorEvent,
   ToolExecutionStartEvent,
   ToolPermissionDeniedEvent,
@@ -14,6 +13,7 @@ import type {
 
 import type { InterfaceId } from "../channels/types.js";
 import type { CesClient } from "../credential-execution/client.js";
+import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import type { SecretPromptResult } from "../permissions/secret-prompter.js";
 import type { ContentBlock } from "../providers/types.js";
 import type { TrustClass } from "../runtime/actor-trust-resolver.js";
@@ -63,7 +63,6 @@ export type {
   ProxyEnvVars,
   SensitiveOutputBinding,
   SensitiveOutputKind,
-  ToolDefinition,
   ToolExecutionErrorEvent,
   ToolExecutionStartEvent,
   ToolPermissionDeniedEvent,
@@ -75,19 +74,7 @@ export { RiskLevel } from "@vellumai/skill-host-contracts";
 // Assistant-side concrete overlays
 // ---------------------------------------------------------------------------
 
-/**
- * Public, narrow subset of {@link ToolExecutionResult} that plugin-authored
- * tools are responsible for producing. Re-exported from
- * `@vellumai/plugin-api` as `ToolExecutionResult` — the type name plugin
- * authors actually import. The daemon-internal version below extends
- * this and adds runtime-only fields (risk metadata, approval
- * bookkeeping, sensitive-output bindings, etc.) that the executor
- * populates around the call — plugins MUST NOT set those.
- *
- * Adding fields here is a non-breaking change; renaming or removing
- * fields is breaking and gated on a major bump of `@vellumai/plugin-api`.
- */
-export interface PluginToolExecutionResult {
+export interface ToolExecutionResult {
   /** Textual result shown to the model in the tool-result block. Empty string is valid. */
   content: string;
   /** When true, the agent loop treats `content` as an error and may surface it / retry. */
@@ -104,9 +91,6 @@ export interface PluginToolExecutionResult {
    * the LLM voluntarily end its turn.
    */
   yieldToUser?: boolean;
-}
-
-export interface ToolExecutionResult extends PluginToolExecutionResult {
   diff?: DiffInfo;
   /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
   contentBlocks?: ContentBlock[];
@@ -163,6 +147,9 @@ export interface ToolExecutionResult extends PluginToolExecutionResult {
    * approval flow transparently.
    */
   cesApprovalRequired?: ApprovalRequired;
+  /** Structured activity metadata for client rendering (web search, web fetch, etc).
+   *  Populated by daemon-internal tools; plugins must not set this. */
+  activityMetadata?: ToolActivityMetadata;
 }
 
 export type ProxyToolResolver = (
@@ -207,20 +194,7 @@ export type ToolLifecycleEventHandler = (
   event: ToolLifecycleEvent,
 ) => void | Promise<void>;
 
-/**
- * Public, narrow subset of {@link ToolContext} handed to plugin-authored
- * tools. Re-exported from `@vellumai/plugin-api` as `ToolContext` — the
- * type name plugin authors actually import. The daemon-internal version
- * below extends this and adds host-only fields (CES client, trust class,
- * lifecycle handlers, requester metadata, host-bash proxy, etc.). Plugin
- * tools see this shape only — the runtime still hands them the full
- * {@link ToolContext} value, but the structural extension here guarantees
- * the assignment without a manual cast.
- *
- * Adding fields here is a non-breaking change; renaming or removing
- * fields is breaking and gated on a major bump of `@vellumai/plugin-api`.
- */
-export interface PluginToolContext {
+export interface ToolContext {
   /** Identifier of the conversation this tool invocation belongs to. */
   conversationId: string;
   /** Working directory the daemon was launched from. */
@@ -231,9 +205,6 @@ export interface PluginToolContext {
   signal?: AbortSignal;
   /** Optional incremental-output callback for streaming tools. Streaming tools should fall back to returning the full result in `content` when this is absent. */
   onOutput?: (chunk: string) => void;
-}
-
-export interface ToolContext extends PluginToolContext {
   /** Logical assistant scope for multi-assistant routing. */
   assistantId?: string;
   /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
@@ -345,11 +316,32 @@ export interface ToolContext extends PluginToolContext {
   sourceActorPrincipalId?: string;
 }
 
-export interface Tool {
-  name: string;
-  description: string;
+/**
+ * Author-facing tool spec — re-exported from `@vellumai/plugin-api`.
+ * Loaders fill documented defaults for omitted fields via `finalizeTool`
+ * in `tool-defaults.ts`.
+ */
+export interface ToolDefinition {
+  /** Human-readable description shown to the model in the tool catalog. */
+  description?: string;
+  /** Author-asserted risk band — low / medium / high. Drives default permission gating. */
+  defaultRiskLevel?: RiskLevel;
+  /** JSON schema describing the tool's input arguments. */
+  input_schema?: object;
+  /** Where the tool runs — sandbox (assistant container) or host (guardian device via proxy). Resolved by `resolveExecutionTarget` if omitted. */
+  executionTarget?: ExecutionTarget;
+  /** Implementation invoked when the model calls the tool. */
+  execute?: (
+    input: Record<string, unknown>,
+    context: ToolContext,
+  ) => Promise<ToolExecutionResult>;
+}
+
+/** Tool after the loader has derived its name and filled defaults. */
+export type LoadedTool = Required<ToolDefinition> & { name: string };
+
+export interface Tool extends LoadedTool {
   category: string;
-  defaultRiskLevel: RiskLevel;
   /** When set to 'proxy', the tool is forwarded to a connected client rather than executed locally. */
   executionMode?: "local" | "proxy";
   /** Whether this tool is a core built-in, provided by a skill, contributed by a plugin, or from an MCP server. */
@@ -364,63 +356,4 @@ export interface Tool {
   ownerSkillVersionHash?: string;
   /** Whether the owning skill is bundled with the daemon (trusted first-party). */
   ownerSkillBundled?: boolean;
-  /** Declared execution target from the skill manifest. Used by resolveExecutionTarget
-   * to accurately label lifecycle events for skill-provided tools. */
-  executionTarget?: ExecutionTarget;
-  getDefinition(): ToolDefinition;
-  execute(
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolExecutionResult>;
 }
-
-/**
- * Plugin-facing tool shape. The narrow surface plugin authors implement;
- * differs from {@link Tool} in four ways:
- * - Plugins declare `input_schema` as a top-level field instead of
- *   implementing `getDefinition()`. The registration boundary synthesizes
- *   `getDefinition()` from `{name, description, input_schema}` before the
- *   tool enters the internal registry.
- * - `name` is derived from the tool file's basename by the external plugin
- *   loader.
- * - `category` is registry-owned and stamped to `"plugin"` when the tool is
- *   registered.
- * - All ownership stamps (`origin`, `ownerPluginId`, etc.) are set
- *   authoritatively by the bootstrap; plugin authors leave them blank.
- *
- * Every author-visible field is optional. The loader fills the four
- * normally-required slots (`description`, `defaultRiskLevel`,
- * `input_schema`, `execute`) with documented defaults when a plugin omits
- * them — see `applyPluginToolDefaults` in `external-plugin-loader.ts`.
- * A nameless, body-less `export default {}` is a valid (if useless) tool;
- * misconfigured tools surface at call time rather than blocking plugin
- * load.
- */
-export type PluginTool = Omit<
-  Tool,
-  "category" | "getDefinition" | "name" | "description" | "defaultRiskLevel"
-> & {
-  description?: string;
-  defaultRiskLevel?: RiskLevel;
-  input_schema?: object;
-  execute?: (
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ) => Promise<ToolExecutionResult>;
-};
-
-/**
- * Plugin tool after the external loader has derived its registry name and
- * filled defaults for any author-omitted fields. All four normally-required
- * slots are guaranteed present.
- */
-export type LoadedPluginTool = PluginTool & {
-  name: string;
-  description: string;
-  defaultRiskLevel: RiskLevel;
-  input_schema: object;
-  execute: (
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ) => Promise<ToolExecutionResult>;
-};

package/src/tools/ui-surface/definitions.ts

@@ -8,7 +8,6 @@
  */
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import type { Tool, ToolExecutionResult } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -36,17 +35,15 @@ export const uiShowTool: Tool = {
     '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
     "- confirmation: { message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }\n" +
     "- dynamic_page: { html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } }\n" +
-    "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n\n" +
+    "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n" +
+    "- task_preferences: {} (no data needed — categories are rendered client-side)\n\n" +
     "Proactively show a task_progress card before multi-step or long-running work (web searches, file operations, research). Show it before your first tool call, then update steps as work progresses.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
+  executionTarget: "host",
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema: {
         type: "object",
         properties: {
           surface_type: {
@@ -59,6 +56,7 @@ export const uiShowTool: Tool = {
               "confirmation",
               "dynamic_page",
               "file_upload",
+              "task_preferences",
             ],
             description: "The type of surface to display",
           },
@@ -107,8 +105,6 @@ export const uiShowTool: Tool = {
         },
         required: ["surface_type", "data"],
       },
-    };
-  },
 
   execute: proxyExecute,
 };
@@ -125,12 +121,9 @@ const uiUpdateTool: Tool = {
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
+  executionTarget: "host",
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema: {
         type: "object",
         properties: {
           surface_id: {
@@ -144,8 +137,6 @@ const uiUpdateTool: Tool = {
         },
         required: ["surface_id", "data"],
       },
-    };
-  },
 
   execute: proxyExecute,
 };
@@ -160,12 +151,9 @@ const uiDismissTool: Tool = {
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
+  executionTarget: "host",
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema: {
         type: "object",
         properties: {
           surface_id: {
@@ -175,8 +163,6 @@ const uiDismissTool: Tool = {
         },
         required: ["surface_id"],
       },
-    };
-  },
 
   execute: proxyExecute,
 };

package/src/types/onboarding-context.ts

@@ -4,6 +4,10 @@ export interface OnboardingContext {
   tone: string;
   userName?: string;
   assistantName?: string;
+  priorAssistants?: string[];
   googleConnected?: boolean;
   googleScopes?: string[];
+  cohort?: string;
+  websiteUrl?: string;
+  contentSourceUrl?: string;
 }

package/src/usage/pricing.ts

@@ -20,9 +20,32 @@ function normalizeTokenCount(value: number | null | undefined): number {
 
 function asRecord(value: unknown): Record<string, unknown> | null {
   if (typeof value !== "object" || value == null) return null;
+  if (Array.isArray(value)) return null;
   return value as Record<string, unknown>;
 }
 
+/**
+ * Extract the provider's untouched `usage` block from a `rawResponse`
+ * payload for opaque end-to-end forwarding (the `raw_usage` column /
+ * telemetry field).
+ *
+ * Returns `null` when there is no usage object to surface. For streaming
+ * providers that pass `rawResponse` as an accumulated array of chunks,
+ * the final element's `usage` is preferred — Anthropic and OpenAI both
+ * stamp the complete tally on the terminal chunk, so taking the last
+ * element captures the post-completion state without re-aggregating.
+ */
+export function extractRawUsage(
+  rawResponse: unknown,
+): Record<string, unknown> | null {
+  if (rawResponse == null) return null;
+  const candidate = Array.isArray(rawResponse)
+    ? rawResponse[rawResponse.length - 1]
+    : rawResponse;
+  const record = asRecord(candidate);
+  return asRecord(record?.usage);
+}
+
 function extractAnthropicCacheCreationFromResponse(
   response: unknown,
 ): AnthropicCacheCreationTokenDetails | null {

package/src/usage/types.ts

@@ -42,6 +42,18 @@ export interface UsageEventInput {
   outputTokens: number;
   cacheCreationInputTokens: number | null;
   cacheReadInputTokens: number | null;
+  /**
+   * The provider's untouched `usage` block (the literal object returned in
+   * the API response), preserved as JSON so downstream consumers can
+   * extract any provider-specific detail without requiring a schema
+   * change. Anthropic nests its TTL breakdown under
+   * `cache_creation.ephemeral_{5m,1h}_input_tokens`; OpenAI nests cached
+   * read counts under `prompt_tokens_details.cached_tokens`; both shapes
+   * are stored as-is. `null` when the provider did not return a usage
+   * block and for rows persisted before the
+   * `260-llm-usage-add-raw-usage` migration.
+   */
+  rawUsage: Record<string, unknown> | null;
   actor: UsageActor;
   conversationId: string | null;
   runId: string | null;

package/src/util/__tests__/favicon.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+
+import { faviconUrlForDomain } from "../favicon.js";
+
+describe("faviconUrlForDomain", () => {
+  test("returns a properly encoded s2 URL for a valid host", () => {
+    expect(faviconUrlForDomain("example.com")).toBe(
+      "https://www.google.com/s2/favicons?domain=example.com&sz=64",
+    );
+  });
+
+  test("lowercases mixed-case hosts before encoding", () => {
+    expect(faviconUrlForDomain("Example.COM")).toBe(
+      "https://www.google.com/s2/favicons?domain=example.com&sz=64",
+    );
+  });
+
+  test("returns undefined for empty input", () => {
+    expect(faviconUrlForDomain("")).toBeUndefined();
+  });
+
+  test("returns undefined for whitespace-only input", () => {
+    expect(faviconUrlForDomain("   ")).toBeUndefined();
+  });
+
+  test("returns undefined for hosts containing a slash", () => {
+    expect(faviconUrlForDomain("example.com/path")).toBeUndefined();
+  });
+
+  test("returns undefined for hosts containing a space", () => {
+    expect(faviconUrlForDomain("example .com")).toBeUndefined();
+  });
+
+  test("URL-encodes unicode/IDN hosts", () => {
+    // Punycode-style raw unicode host should be percent-encoded by encodeURIComponent.
+    const result = faviconUrlForDomain("münchen.de");
+    expect(result).toBe(
+      `https://www.google.com/s2/favicons?domain=${encodeURIComponent("münchen.de")}&sz=64`,
+    );
+    // Sanity check: the encoded form contains percent-encoded bytes for "ü".
+    expect(result).toContain("m%C3%BCnchen.de");
+  });
+
+  test("returns undefined for localhost", () => {
+    expect(faviconUrlForDomain("localhost")).toBeUndefined();
+  });
+
+  test("returns undefined for private IPv4 hosts", () => {
+    expect(faviconUrlForDomain("127.0.0.1")).toBeUndefined();
+    expect(faviconUrlForDomain("10.0.0.5")).toBeUndefined();
+    expect(faviconUrlForDomain("192.168.1.1")).toBeUndefined();
+  });
+
+  test("returns undefined for any raw IPv4 literal — private or public", () => {
+    // We can't tell from the host alone whether an IP belongs to a routable
+    // public host or an internal one, so all IP literals are rejected to avoid
+    // leaking the address to Google when the client renders the icon.
+    expect(faviconUrlForDomain("172.16.0.1")).toBeUndefined();
+    expect(faviconUrlForDomain("8.8.8.8")).toBeUndefined();
+    expect(faviconUrlForDomain("1.1.1.1")).toBeUndefined();
+  });
+
+  test("returns undefined for raw IPv6 literals (bracketed or bare)", () => {
+    expect(faviconUrlForDomain("2001:db8::1")).toBeUndefined();
+    expect(faviconUrlForDomain("[2001:db8::1]")).toBeUndefined();
+  });
+
+  test("strips :port before the private-host check (host:port → undefined for private)", () => {
+    expect(faviconUrlForDomain("localhost:3000")).toBeUndefined();
+    expect(faviconUrlForDomain("127.0.0.1:8080")).toBeUndefined();
+    expect(faviconUrlForDomain("192.168.1.1:443")).toBeUndefined();
+  });
+
+  test("strips :port and encodes only the host (public host with port)", () => {
+    const result = faviconUrlForDomain("example.com:8080");
+    expect(result).toBe(
+      "https://www.google.com/s2/favicons?domain=example.com&sz=64",
+    );
+  });
+
+  test("handles bracketed IPv6 hosts with ports", () => {
+    expect(faviconUrlForDomain("[::1]:8080")).toBeUndefined();
+  });
+});