@alumbwe/anvil 1.0.20 → 1.0.21

package/vendor/@anvil/common/src/util/__tests__/tool-result-media-order.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'bun:test'
+
+import { convertCbToModelMessages } from '../messages'
+
+import type { Message } from '../../types/messages/anvil-message'
+
+/**
+ * preview_screenshot returns [media, json] so the model sees the pixels before
+ * the note. A `media` part becomes a user message (providers reject images
+ * inside a tool message), so emitting parts in their original order put that
+ * user message between the assistant's tool_call and its result — which
+ * providers reject, and which the server's repair then resolves by dropping
+ * both the call and the result.
+ */
+describe('convertMessages — tool results carrying media', () => {
+  const screenshotHistory = (): Message[] => [
+    { role: 'user', content: [{ type: 'text', text: 'take a screenshot' }] },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'tool-call',
+          toolCallId: 'shot-1',
+          toolName: 'preview_screenshot',
+          input: {},
+        },
+      ],
+    },
+    {
+      role: 'tool',
+      toolName: 'preview_screenshot',
+      toolCallId: 'shot-1',
+      content: [
+        { type: 'media', data: 'BASE64PNG', mediaType: 'image/png' },
+        { type: 'json', value: { ok: true } },
+      ],
+    },
+  ]
+
+  it('puts the tool result immediately after the call, image after', () => {
+    const converted = convertCbToModelMessages({
+      messages: screenshotHistory(),
+    })
+
+    expect(converted.map((m) => m.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+      'user',
+    ])
+  })
+
+  it('keeps both the result and the image', () => {
+    const converted = convertCbToModelMessages({
+      messages: screenshotHistory(),
+    })
+    const serialized = JSON.stringify(converted)
+
+    expect(serialized).toContain('BASE64PNG')
+    expect(serialized).toContain('shot-1')
+  })
+
+  it('is unaffected when a tool returns json only', () => {
+    const converted = convertCbToModelMessages({
+      messages: [
+        {
+          role: 'tool',
+          toolName: 'read_files',
+          toolCallId: 'r1',
+          content: [{ type: 'json', value: { files: [] } }],
+        },
+      ] as Message[],
+    })
+
+    expect(converted.map((m) => m.role)).toEqual(['tool'])
+  })
+})
+
+describe('convertMessages — tool results with media but no json', () => {
+  it('still answers the call, so it is not left unpaired', () => {
+    // `mediaToolResult` produces media-only output. Emitting just the user
+    // message would leave the assistant's tool_call permanently unanswered.
+    const converted = convertCbToModelMessages({
+      messages: [
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: 'tool-call',
+              toolCallId: 'shot-2',
+              toolName: 'preview_screenshot',
+              input: {},
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          toolName: 'preview_screenshot',
+          toolCallId: 'shot-2',
+          content: [{ type: 'media', data: 'ONLYIMG', mediaType: 'image/png' }],
+        },
+      ] as Message[],
+    })
+
+    expect(converted.map((m) => m.role)).toEqual(['assistant', 'tool', 'user'])
+    expect(JSON.stringify(converted)).toContain('ONLYIMG')
+  })
+})

package/vendor/@anvil/common/src/util/__tests__/ttft-histogram.test.ts

@@ -0,0 +1,180 @@
+/**
+ * The /latency dashboard's p50/p95 come out of this bucketing rather than out of
+ * percentile_cont over `message`, so what these tests guard is the size of the
+ * error that substitution introduces — and that it stays a bounded *relative*
+ * error at every latency, which is what keeps models ranked correctly against
+ * each other.
+ */
+import { describe, expect, it } from 'bun:test'
+
+import {
+  TTFT_HISTOGRAM_BASE,
+  TTFT_HISTOGRAM_BUCKET_COUNT,
+  ttftBucketIndex,
+  ttftBucketMs,
+  ttftPercentileFromHistogram,
+} from '../ttft-histogram'
+
+/** Exact percentile with the same nearest-rank definition the histogram uses. */
+function exactPercentile(samples: number[], quantile: number): number {
+  const sorted = [...samples].sort((a, b) => a - b)
+  const target = sorted.length * quantile
+  let cumulative = 0
+  for (const value of sorted) {
+    cumulative += 1
+    if (cumulative >= target) return value
+  }
+  return sorted[sorted.length - 1]
+}
+
+function histogramOf(samples: number[]): Map<number, number> {
+  const histogram = new Map<number, number>()
+  for (const sample of samples) {
+    const bucket = ttftBucketIndex(sample)
+    histogram.set(bucket, (histogram.get(bucket) ?? 0) + 1)
+  }
+  return histogram
+}
+
+/** Deterministic LCG — a seeded generator keeps failures reproducible. */
+function makeRandom(seed: number): () => number {
+  let state = seed
+  return () => {
+    state = (state * 1664525 + 1013904223) % 4294967296
+    return state / 4294967296
+  }
+}
+
+describe('ttftBucketIndex', () => {
+  it('is monotonic in latency', () => {
+    let previous = -1
+    for (const ms of [0, 1, 10, 100, 500, 1000, 2000, 5000, 30_000, 120_000]) {
+      const bucket = ttftBucketIndex(ms)
+      expect(bucket).toBeGreaterThanOrEqual(previous)
+      previous = bucket
+    }
+  })
+
+  it('clamps degenerate samples into the first bucket instead of -Infinity', () => {
+    // log(0) is -Infinity, which would poison every downstream sum.
+    expect(ttftBucketIndex(0)).toBe(0)
+    expect(ttftBucketIndex(0.4)).toBe(0)
+    expect(ttftBucketIndex(1)).toBe(0)
+    expect(Number.isFinite(ttftBucketMs(ttftBucketIndex(0)))).toBe(true)
+  })
+
+  it('clamps pathological samples into the last bucket', () => {
+    const last = TTFT_HISTOGRAM_BUCKET_COUNT - 1
+    expect(ttftBucketIndex(Number.MAX_SAFE_INTEGER)).toBe(last)
+    // The top edge is far past any real TTFT, so nothing legitimate saturates.
+    expect(ttftBucketIndex(60 * 60 * 1000)).toBeLessThan(last)
+  })
+
+  it('keeps every reported value within half a bucket, plus ms rounding', () => {
+    // The geometric half-width is the real guarantee; the extra 0.5ms is
+    // ttftBucketMs rounding to whole milliseconds, which only matters at
+    // latencies far below anything a model produces.
+    const halfWidth = (TTFT_HISTOGRAM_BASE - 1) / 2
+    for (let ms = 1; ms <= 300_000; ms = Math.ceil(ms * 1.017)) {
+      const reported = ttftBucketMs(ttftBucketIndex(ms))
+      expect(Math.abs(reported - ms)).toBeLessThanOrEqual(
+        ms * halfWidth + 0.5 + 1e-9,
+      )
+    }
+  })
+
+  it('keeps the relative error under 1.6% across the range the page renders', () => {
+    // This is what the dashboard rests on: ~1.5% of a 2s median is ~30ms, far
+    // below the gap between any two models on the page. The bound is 1.6% and
+    // not 1.5% because whole-millisecond rounding adds up to 0.5ms on top of
+    // the geometric half-width, which is only visible below ~200ms. Measured
+    // worst case over this range is 1.544%, at 259ms.
+    for (let ms = 200; ms <= 300_000; ms = Math.ceil(ms * 1.017)) {
+      const reported = ttftBucketMs(ttftBucketIndex(ms))
+      expect(Math.abs(reported - ms) / ms).toBeLessThanOrEqual(0.016)
+    }
+  })
+})
+
+describe('ttftPercentileFromHistogram', () => {
+  it('returns null for an empty histogram rather than 0', () => {
+    // 0 would render as a real, extremely fast measurement.
+    expect(ttftPercentileFromHistogram([], 0.5)).toBeNull()
+    expect(ttftPercentileFromHistogram([[10, 0]], 0.5)).toBeNull()
+  })
+
+  it('tracks exact percentiles on a realistic long-tailed distribution', () => {
+    // Log-normal-ish: a tight body around ~1.8s with a slow tail, which is what
+    // the real TTFT samples look like.
+    const random = makeRandom(20260728)
+    const samples = Array.from({ length: 50_000 }, () => {
+      const u = Math.max(random(), 1e-9)
+      const v = Math.max(random(), 1e-9)
+      const normal = Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v)
+      return Math.max(1, Math.round(Math.exp(7.5 + 0.6 * normal)))
+    })
+
+    const histogram = histogramOf(samples)
+    for (const quantile of [0.5, 0.9, 0.95, 0.99]) {
+      const approximate = ttftPercentileFromHistogram(histogram, quantile)!
+      const exact = exactPercentile(samples, quantile)
+      expect(Math.abs(approximate - exact) / exact).toBeLessThan(0.02)
+    }
+  })
+
+  it('preserves the ordering between two models a few percent apart', () => {
+    // The page sorts by p50, and the real DeepSeek/MiniMax gap is ~8%. Bucketing
+    // must not be able to flip that.
+    const slower = histogramOf(
+      Array.from({ length: 10_000 }, (_, i) => 1981 + (i % 200)),
+    )
+    const faster = histogramOf(
+      Array.from({ length: 10_000 }, (_, i) => 1822 + (i % 200)),
+    )
+
+    expect(ttftPercentileFromHistogram(faster, 0.5)!).toBeLessThan(
+      ttftPercentileFromHistogram(slower, 0.5)!,
+    )
+  })
+
+  it('merges histograms additively, which is what hourly rollup relies on', () => {
+    // Percentiles are not additive, but counts are: a window percentile must
+    // equal the percentile of the merged distribution, not a blend of the parts.
+    const hourA = Array.from({ length: 3_000 }, (_, i) => 800 + (i % 400))
+    const hourB = Array.from({ length: 1_000 }, (_, i) => 9_000 + (i % 900))
+
+    const merged = histogramOf([...hourA, ...hourB])
+    const combined = new Map(histogramOf(hourA))
+    for (const [bucket, count] of histogramOf(hourB)) {
+      combined.set(bucket, (combined.get(bucket) ?? 0) + count)
+    }
+
+    expect(ttftPercentileFromHistogram(combined, 0.5)).toBe(
+      ttftPercentileFromHistogram(merged, 0.5),
+    )
+    expect(ttftPercentileFromHistogram(combined, 0.95)).toBe(
+      ttftPercentileFromHistogram(merged, 0.95),
+    )
+    // And the merged p95 lands in the slow hour, not on an average of the two.
+    expect(ttftPercentileFromHistogram(merged, 0.95)!).toBeGreaterThan(8_000)
+  })
+
+  it('does not require the caller to pre-sort buckets', () => {
+    const pairs: [number, number][] = [
+      [300, 10],
+      [100, 80],
+      [200, 10],
+    ]
+    expect(ttftPercentileFromHistogram(pairs, 0.5)).toBe(ttftBucketMs(100))
+    expect(ttftPercentileFromHistogram([...pairs].reverse(), 0.5)).toBe(
+      ttftBucketMs(100),
+    )
+  })
+
+  it('reports the slowest occupied bucket for a quantile of 1', () => {
+    const histogram = histogramOf([100, 200, 30_000])
+    expect(ttftPercentileFromHistogram(histogram, 1)).toBe(
+      ttftBucketMs(ttftBucketIndex(30_000)),
+    )
+  })
+})

package/vendor/@anvil/common/src/util/__tests__/with-timeout.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it, spyOn } from 'bun:test'
+
+import { withTimeout } from '../promise'
+
+describe('withTimeout', () => {
+  it('clears its timer when the wrapped promise rejects', async () => {
+    const timeoutId = 123 as unknown as ReturnType<typeof setTimeout>
+    const setTimeoutSpy = spyOn(globalThis, 'setTimeout').mockReturnValue(
+      timeoutId,
+    )
+    const clearTimeoutSpy = spyOn(globalThis, 'clearTimeout')
+    const error = new Error('expected rejection')
+
+    try {
+      await expect(withTimeout(Promise.reject(error), 15_000)).rejects.toBe(
+        error,
+      )
+      expect(clearTimeoutSpy).toHaveBeenCalledWith(timeoutId)
+    } finally {
+      setTimeoutSpy.mockRestore()
+      clearTimeoutSpy.mockRestore()
+    }
+  })
+})

package/vendor/@anvil/common/src/util/__tests__/zoned-time.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test'
+
+import { getZonedDayBounds, getZonedWeekBounds } from '../zoned-time'
+
+describe('getZonedDayBounds', () => {
+  test('returns the current Pacific day bounds on a normal day', () => {
+    const bounds = getZonedDayBounds(
+      new Date('2026-04-17T16:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-04-17T07:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-04-18T07:00:00.000Z')
+  })
+
+  test('handles the shorter spring-forward Pacific day', () => {
+    const bounds = getZonedDayBounds(
+      new Date('2026-03-08T09:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-03-08T08:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-03-09T07:00:00.000Z')
+  })
+
+  test('handles the longer fall-back Pacific day', () => {
+    const bounds = getZonedDayBounds(
+      new Date('2026-11-01T09:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-11-01T07:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-11-02T08:00:00.000Z')
+  })
+})
+
+describe('getZonedWeekBounds', () => {
+  // The week is Monday-anchored by default. 2026-04-17 is a Friday; its week
+  // starts Monday 2026-04-13 and resets the following Monday 2026-04-20, both at
+  // Pacific midnight (07:00Z during PDT).
+  test('returns Monday→Monday Pacific bounds for a mid-week day', () => {
+    const bounds = getZonedWeekBounds(
+      new Date('2026-04-17T16:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-04-13T07:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-04-20T07:00:00.000Z')
+  })
+
+  test('groups Sunday into the week that started the prior Monday', () => {
+    // 2026-04-19 is the Sunday of the same week, so it must yield identical
+    // bounds to the Friday case (Sunday is the LAST day of a Monday-week).
+    const bounds = getZonedWeekBounds(
+      new Date('2026-04-19T18:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-04-13T07:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-04-20T07:00:00.000Z')
+  })
+
+  test('handles the spring-forward week (start in PST, reset in PDT)', () => {
+    // 2026-03-08 (DST switch day) is a Sunday; its week started Monday
+    // 2026-03-02 at PST midnight (08:00Z) and resets Monday 2026-03-09 at PDT
+    // midnight (07:00Z) — the week itself is one hour short.
+    const bounds = getZonedWeekBounds(
+      new Date('2026-03-08T18:00:00Z'),
+      'America/Los_Angeles',
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-03-02T08:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-03-09T07:00:00.000Z')
+  })
+
+  test('honors a Sunday week start when requested', () => {
+    // weekStartsOn=0 → the Friday 2026-04-17 belongs to the week starting
+    // Sunday 2026-04-12.
+    const bounds = getZonedWeekBounds(
+      new Date('2026-04-17T16:00:00Z'),
+      'America/Los_Angeles',
+      0,
+    )
+
+    expect(bounds.startsAt.toISOString()).toBe('2026-04-12T07:00:00.000Z')
+    expect(bounds.resetsAt.toISOString()).toBe('2026-04-19T07:00:00.000Z')
+  })
+})

package/vendor/@anvil/common/src/util/ad-user-agent.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser-like user agent passed to ad providers for targeting and fraud
+ * screening. Keep this shared by every native client so one surface cannot
+ * accidentally fall back to a runtime UA such as `Bun/<version>`.
+ *
+ * Chrome version needs bumping periodically because stale UAs look bot-like to
+ * ad networks. Last bumped: 2026-04-21. Revisit roughly every six months.
+ */
+const AD_CHROME_VERSION = '124.0.0.0'
+
+const AD_USER_AGENTS: Record<string, string> = {
+  darwin: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${AD_CHROME_VERSION} Safari/537.36`,
+  win32: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${AD_CHROME_VERSION} Safari/537.36`,
+  linux: `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${AD_CHROME_VERSION} Safari/537.36`,
+}
+
+export function getAdUserAgent(platform: string = process.platform): string {
+  const platformKey =
+    platform === 'macos'
+      ? 'darwin'
+      : platform === 'windows'
+        ? 'win32'
+        : platform
+  return AD_USER_AGENTS[platformKey] ?? AD_USER_AGENTS.linux
+}

package/vendor/@anvil/common/src/util/agent-file-utils.ts

@@ -0,0 +1,110 @@
+/**
+ * Utility functions for working with agent template files
+ */
+
+import type { DynamicAgentTemplate } from '../types/dynamic-agent-template'
+
+/**
+ * Determines if a file is a valid custom agent template file.
+ *
+ * Custom agent files must:
+ * - End with .ts extension
+ * - NOT end with .d.ts (TypeScript declaration files)
+ *
+ * @param fileName - The name of the file to check
+ * @returns true if the file is a valid custom agent template
+ */
+export function isCustomAgentFile(fileName: string): boolean {
+  return fileName.endsWith('.ts') && !fileName.endsWith('.d.ts')
+}
+
+/**
+ * Filters a list of file names to only include valid custom agent template files.
+ *
+ * @param fileNames - Array of file names to filter
+ * @returns Array of file names that are valid custom agent templates
+ */
+export function filterCustomAgentFiles(fileNames: string[]): string[] {
+  return fileNames.filter(isCustomAgentFile)
+}
+
+/**
+ * Filters an object of file paths/templates to only include valid custom agent templates.
+ *
+ * @param agentTemplates - Object with file paths as keys
+ * @returns Filtered object containing only valid custom agent templates
+ */
+export function filterCustomAgentTemplates<T>(
+  agentTemplates: Record<string, T>,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(agentTemplates).filter(([filePath]) =>
+      isCustomAgentFile(filePath),
+    ),
+  )
+}
+
+/**
+ * Extracts the agent ID from a TypeScript file name.
+ *
+ * @param fileName - The TypeScript file name (e.g., 'my-agent.ts')
+ * @returns The agent ID (e.g., 'my-agent')
+ */
+export function extractAgentIdFromFileName(fileName: string): string {
+  return fileName.replace('.ts', '')
+}
+
+/**
+ * Filters agent templates to include only valid ones, excluding generated files and invalid entries.
+ *
+ * This method handles various edge cases:
+ * - TypeScript declaration files (.d.ts) generated by tools
+ * - Frontend key normalization (strips .ts extensions)
+ * - Files without extensions
+ * - Invalid or empty template data
+ *
+ * @param agentTemplates - Object with file paths as keys and templates as values
+ * @returns Filtered object containing only valid agent templates
+ */
+export function filterValidAgentTemplates(
+  agentTemplates: Record<string, DynamicAgentTemplate>,
+): Record<string, DynamicAgentTemplate> {
+  return Object.fromEntries(
+    Object.entries(agentTemplates).filter(([key, template]) => {
+      // Skip if no template data
+      if (!template) {
+        return false
+      }
+
+      // Skip TypeScript declaration files (.d.ts) - these are generated artifacts
+      if (key.endsWith('.d.ts')) {
+        return false
+      }
+
+      // Skip files with invalid extensions (but allow files without extensions)
+      // This handles cases where frontend strips .ts but we want to exclude other extensions
+      if (key.includes('.') && !key.endsWith('.ts')) {
+        // Allow common valid extensions for agent templates
+        const validExtensions = ['.ts', '.js', '.mjs']
+        const hasValidExtension = validExtensions.some((ext) =>
+          key.endsWith(ext),
+        )
+        if (!hasValidExtension) {
+          return false
+        }
+      }
+
+      // Skip if template doesn't have required fields
+      if (!template.id || typeof template.id !== 'string') {
+        return false
+      }
+
+      // Skip if template has invalid structure
+      if (typeof template !== 'object') {
+        return false
+      }
+
+      return true
+    }),
+  )
+}

package/vendor/@anvil/common/src/util/agent-id-parsing.ts

@@ -0,0 +1,136 @@
+/**
+ * Parse agent ID to extract publisher, agent name, and version
+ * Supports formats:
+ * - publisher/agentId[@version]
+ * - agentId[@version] (no publisher)
+ */
+export function parseAgentId(fullAgentId: string): {
+  publisherId?: string
+  agentId?: string
+  version?: string
+  givenAgentId: string
+} {
+  // Check if it's in the publisher/agent-id[@version] format
+  const parts = fullAgentId.split('/')
+
+  if (parts.length === 2) {
+    // Full format: publisher/agentId[@version]
+    const [publisherId, agentNameWithVersion] = parts
+
+    if (!publisherId || !agentNameWithVersion) {
+      return {
+        publisherId: undefined,
+        agentId: undefined,
+        version: undefined,
+        givenAgentId: fullAgentId,
+      }
+    }
+
+    // Check for version suffix
+    const versionMatch = agentNameWithVersion.match(/^(.+)@(.+)$/)
+    if (versionMatch) {
+      const [, agentId, version] = versionMatch
+      return { publisherId, agentId, version, givenAgentId: fullAgentId }
+    }
+
+    return {
+      publisherId,
+      agentId: agentNameWithVersion,
+      givenAgentId: fullAgentId,
+    }
+  } else if (parts.length === 1) {
+    // Just agent name (for backward compatibility)
+    const agentNameWithVersion = parts[0]
+
+    if (!agentNameWithVersion) {
+      return {
+        publisherId: undefined,
+        agentId: undefined,
+        version: undefined,
+        givenAgentId: fullAgentId,
+      }
+    }
+
+    // Check for version suffix
+    const versionMatch = agentNameWithVersion.match(/^(.+)@(.+)$/)
+    if (versionMatch) {
+      const [, agentId, version] = versionMatch
+      return {
+        publisherId: undefined,
+        agentId,
+        version,
+        givenAgentId: fullAgentId,
+      }
+    }
+
+    return {
+      publisherId: undefined,
+      agentId: agentNameWithVersion,
+      version: undefined,
+      givenAgentId: fullAgentId,
+    }
+  }
+
+  return {
+    publisherId: undefined,
+    agentId: undefined,
+    version: undefined,
+    givenAgentId: fullAgentId,
+  }
+}
+
+/**
+ * Parse published agent ID to extract publisher, agent name, and optionally version
+ *
+ * If the agent ID is not in the publisher/agent format, return null
+ */
+export function parsePublishedAgentId(fullAgentId: string): {
+  publisherId: string
+  agentId: string
+  version?: string
+} | null {
+  const { publisherId, agentId, version } = parseAgentId(fullAgentId)
+  if (!publisherId || !agentId) {
+    return null
+  }
+  return {
+    publisherId,
+    agentId,
+    version,
+  }
+}
+
+/**
+ * Normalizes an agent ID for lookup by accepting underscores as aliases for
+ * hyphens in the agent-name segment. Publisher IDs and version strings are
+ * preserved as written.
+ */
+export function normalizeAgentIdForLookup(fullAgentId: string): string {
+  const parts = fullAgentId.split('/')
+  if (parts.length > 2) {
+    return fullAgentId
+  }
+
+  const normalizeNameWithVersion = (agentNameWithVersion: string) => {
+    const versionStart = agentNameWithVersion.indexOf('@')
+    const agentName =
+      versionStart === -1
+        ? agentNameWithVersion
+        : agentNameWithVersion.slice(0, versionStart)
+    const version =
+      versionStart === -1 ? '' : agentNameWithVersion.slice(versionStart)
+
+    return `${agentName.replace(/_/g, '-')}${version}`
+  }
+
+  if (parts.length === 1) {
+    return normalizeNameWithVersion(fullAgentId)
+  }
+
+  const [publisherId, agentNameWithVersion] = parts
+  if (!publisherId || !agentNameWithVersion) {
+    return fullAgentId
+  }
+
+  return `${publisherId}/${normalizeNameWithVersion(agentNameWithVersion)}`
+}