@tonyclaw/llm-inspector 1.18.0 → 1.18.2

package/src/components/ProxyViewer.tsx

@@ -1,5 +1,5 @@
 import { type JSX, useCallback, useEffect, useMemo, useRef, useState, Suspense } from "react";
-import { Download } from "lucide-react";
+import { ArrowLeft, Check, Copy, Download, Plus } from "lucide-react";
 
 import type { CapturedLog } from "../proxy/schemas";
 import { exportLogsAsZip } from "../lib/export-logs";
@@ -9,7 +9,9 @@ import { ConversationGroup, groupLogsByConversation } from "./proxy-viewer";
 
 import { CrabLogo } from "./ui/crab-logo";
 import { crabVariants } from "./ui/crab-variants";
+import { McpLogo } from "./ui/mcp-logo";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./ui/select";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./ui/tooltip";
 import { SettingsDialog } from "./providers/SettingsDialog";
 import { computeCacheTrends } from "./proxy-viewer/cacheTrend";
 import { LazyCompareDrawer } from "./proxy-viewer/lazy";
@@ -31,6 +33,28 @@ function computeTokenSummary(logs: CapturedLog[]): { totalIn: number; totalOut:
   return { totalIn, totalOut };
 }
 
+function formatTimeRange(logs: CapturedLog[]): string | null {
+  const first = logs[0];
+  const last = logs[logs.length - 1];
+  if (first === undefined || last === undefined) return null;
+  const format = (iso: string): string =>
+    new Date(iso).toLocaleTimeString([], {
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+  return `${format(first.timestamp)} - ${format(last.timestamp)}`;
+}
+
+function getFirstUserAgent(logs: CapturedLog[]): string | null {
+  for (const log of logs) {
+    if (log.userAgent !== null && log.userAgent !== undefined && log.userAgent !== "") {
+      return log.userAgent;
+    }
+  }
+  return null;
+}
+
 function CopyableCommand({ command }: { command: string }): JSX.Element {
   const [copied, setCopied] = useState(false);
 
@@ -83,6 +107,97 @@ function CopyableCommand({ command }: { command: string }): JSX.Element {
   );
 }
 
+function McpReadyBadge(): JSX.Element {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <span className="inline-flex h-7 items-center gap-2 rounded-md border border-cyan-400/30 bg-cyan-500/10 px-2.5 font-mono text-[11px] font-medium text-cyan-300 shadow-[0_0_16px_rgba(34,211,238,0.08)]">
+            <span className="size-1.5 rounded-full bg-emerald-300 shadow-[0_0_8px_rgba(110,231,183,0.8)]" />
+            MCP Ready
+            <span className="hidden text-cyan-200/70 sm:inline">/api/mcp</span>
+          </span>
+        </TooltipTrigger>
+        <TooltipContent sideOffset={8} className="max-w-[320px] text-left leading-relaxed">
+          Coding agents can inspect logs, replay requests, test providers, and debug sessions
+          through MCP at /api/mcp.
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
+
+function SessionContextBar({
+  sessionId,
+  logs,
+  totalIn,
+  totalOut,
+}: {
+  sessionId: string;
+  logs: CapturedLog[];
+  totalIn: number;
+  totalOut: number;
+}): JSX.Element {
+  const [copied, setCopied] = useState(false);
+  const timeRange = useMemo(() => formatTimeRange(logs), [logs]);
+  const userAgent = useMemo(() => getFirstUserAgent(logs), [logs]);
+
+  const handleCopyLink = useCallback(() => {
+    void window.navigator.clipboard.writeText(window.location.href).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  }, []);
+
+  return (
+    <div className="mb-4 flex items-center gap-3 border border-border rounded-md bg-muted/20 px-3 py-2 text-xs">
+      <a
+        href="/"
+        className="inline-flex size-8 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        aria-label="Back to all sessions"
+        title="Back to all sessions"
+      >
+        <ArrowLeft className="size-3.5" />
+      </a>
+      <div className="min-w-0 flex-1">
+        <div className="flex min-w-0 items-center gap-2">
+          <span className="font-mono font-semibold text-purple-400/90 truncate" title={sessionId}>
+            {truncateSessionId(sessionId)}
+          </span>
+          {userAgent !== null && (
+            <span
+              className="font-mono text-muted-foreground truncate max-w-[220px]"
+              title={userAgent}
+            >
+              {userAgent}
+            </span>
+          )}
+        </div>
+        <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-muted-foreground">
+          <span>
+            {logs.length} request{logs.length !== 1 ? "s" : ""}
+          </span>
+          {timeRange !== null && <span>{timeRange}</span>}
+          {(totalIn > 0 || totalOut > 0) && (
+            <span className="font-mono">
+              {formatTokens(totalIn)} in / {formatTokens(totalOut)} out
+            </span>
+          )}
+        </div>
+      </div>
+      <button
+        type="button"
+        onClick={handleCopyLink}
+        className="inline-flex size-8 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        aria-label={copied ? "Copied session link" : "Copy session link"}
+        title={copied ? "Copied session link" : "Copy session link"}
+      >
+        {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+      </button>
+    </div>
+  );
+}
+
 export type ProxyViewerProps = {
   logs: CapturedLog[];
   sessions: string[];
@@ -101,6 +216,12 @@ export type ProxyViewerProps = {
   strip: boolean;
   /** Slow-response threshold in seconds. `0` disables the warning indicator. */
   slowResponseThresholdSeconds: number;
+  /** Hide the session filter dropdown. Used on `/session/$id` routes where
+   *  the session is already pinned by the URL and the dropdown would just
+   *  fight the URL state. */
+  hideSessionFilter?: boolean;
+  /** Session id pinned by a `/session/$id` route. Enables session-page chrome. */
+  pinnedSessionId?: string;
 };
 
 export function ProxyViewer({
@@ -117,6 +238,8 @@ export function ProxyViewer({
   onViewModeChange,
   strip,
   slowResponseThresholdSeconds,
+  hideSessionFilter = false,
+  pinnedSessionId,
 }: ProxyViewerProps): JSX.Element {
   const { totalIn, totalOut } = useMemo(() => computeTokenSummary(logs), [logs]);
   const [exporting, setExporting] = useState(false);
@@ -140,6 +263,15 @@ export function ProxyViewer({
     };
   }, []);
 
+  useEffect(() => {
+    if (pinnedSessionId === undefined) {
+      document.title = "LLM Inspector";
+      return;
+    }
+    const requestLabel = logs.length === 1 ? "1 req" : `${logs.length} req`;
+    document.title = `${truncateSessionId(pinnedSessionId)} - ${requestLabel} - LLM Inspector`;
+  }, [logs.length, pinnedSessionId]);
+
   const handleExport = useCallback(async () => {
     setExporting(true);
     try {
@@ -172,73 +304,92 @@ export function ProxyViewer({
   return (
     <div className="max-w-[1400px] xl:max-w-[1600px] 2xl:max-w-[1800px] mx-auto px-6 pb-6">
       {/* Brand row */}
-      <div className="flex items-end pt-6 pb-8 relative">
-        <h1 className="text-lg font-bold flex items-end gap-2 absolute left-1/2 -translate-x-1/2 whitespace-nowrap">
-          {/* Crab family — hover to animate together */}
-          <span className="flex items-end gap-1 group cursor-default" aria-hidden="true">
-            <CrabLogo className="size-10 text-amber-500 transition-all duration-300 group-hover:scale-125 group-hover:-translate-y-1.5" />
-            <span className="flex items-end gap-0.5">
-              {crabVariants.map((Crab, i) => {
-                const color = [
-                  "text-amber-500",
-                  "text-rose-500",
-                  "text-sky-500",
-                  "text-emerald-500",
-                  "text-violet-500",
-                  "text-orange-500",
-                  "text-cyan-500",
-                  "text-pink-500",
-                  "text-lime-500",
-                  "text-blue-500",
-                  "text-yellow-500",
-                  "text-fuchsia-500",
-                ][i];
-                const entranceClass =
-                  crabEntrancePhase === "hidden"
-                    ? "opacity-0 scale-0"
-                    : crabEntrancePhase === "playing"
-                      ? "animate-crab-piano-pop"
-                      : "";
-                return (
-                  <Crab
-                    key={i}
-                    className={`size-5 ${color} transition-all duration-300 ease-out group-hover:scale-125 group-hover:-translate-y-1 ${entranceClass}`}
-                    style={{
-                      transitionDelay: `${i * 50}ms`,
-                      ...(crabEntrancePhase === "playing"
-                        ? { animationDelay: `${i * 400}ms` }
-                        : {}),
-                    }}
-                  />
-                );
-              })}
+      <div className="grid grid-cols-[1fr_auto_1fr] items-start gap-3 pt-6 pb-8">
+        <div />
+        <h1 className="flex min-w-0 flex-col items-center gap-2 text-center">
+          <span className="flex max-w-[calc(100vw-7rem)] items-end gap-2 whitespace-nowrap">
+            {/* Crab family — hover to animate together */}
+            <span className="flex shrink-0 items-end gap-1 group cursor-default" aria-hidden="true">
+              <CrabLogo className="size-10 text-amber-500 transition-all duration-300 group-hover:scale-125 group-hover:-translate-y-1.5" />
+              <span className="hidden items-end gap-0.5 sm:flex">
+                {crabVariants.map((Crab, i) => {
+                  const color = [
+                    "text-amber-500",
+                    "text-rose-500",
+                    "text-sky-500",
+                    "text-emerald-500",
+                    "text-violet-500",
+                    "text-orange-500",
+                    "text-cyan-500",
+                    "text-pink-500",
+                    "text-lime-500",
+                    "text-blue-500",
+                    "text-yellow-500",
+                    "text-fuchsia-500",
+                  ][i];
+                  const entranceClass =
+                    crabEntrancePhase === "hidden"
+                      ? "opacity-0 scale-0"
+                      : crabEntrancePhase === "playing"
+                        ? "animate-crab-piano-pop"
+                        : "";
+                  return (
+                    <Crab
+                      key={i}
+                      className={`size-5 ${color} transition-all duration-300 ease-out group-hover:scale-125 group-hover:-translate-y-1 ${entranceClass}`}
+                      style={{
+                        transitionDelay: `${i * 50}ms`,
+                        ...(crabEntrancePhase === "playing"
+                          ? { animationDelay: `${i * 400}ms` }
+                          : {}),
+                      }}
+                    />
+                  );
+                })}
+              </span>
             </span>
+            <span className="flex min-w-0 items-baseline gap-2 pl-1">
+              <span className="truncate text-lg font-bold">LLM Inspector</span>
+              <span className="shrink-0 font-mono text-xs font-semibold text-muted-foreground">
+                v{packageJson.version}
+              </span>
+            </span>
+            <Plus className="size-4 shrink-0 text-muted-foreground/70" aria-hidden="true" />
+            <McpLogo className="size-10 shrink-0" />
           </span>
-          <span className="flex items-baseline gap-2">
-            LLM Inspector
-            <span className="text-xs text-muted-foreground font-mono">v{packageJson.version}</span>
-          </span>
+          <McpReadyBadge />
         </h1>
-        <div className="ml-auto">
+        <div className="justify-self-end">
           <SettingsDialog />
         </div>
       </div>
 
+      {pinnedSessionId !== undefined && (
+        <SessionContextBar
+          sessionId={pinnedSessionId}
+          logs={logs}
+          totalIn={totalIn}
+          totalOut={totalOut}
+        />
+      )}
+
       {/* Controls + Filters */}
       <div className="flex items-center gap-3 mb-4">
-        <Select value={selectedSession} onValueChange={onSessionChange}>
-          <SelectTrigger className="flex-1 max-w-[350px] text-xs">
-            <SelectValue placeholder="All sessions" />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="__all__">All sessions</SelectItem>
-            {sessions.map((s) => (
-              <SelectItem key={s} value={s}>
-                {truncateSessionId(s)}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+        {!hideSessionFilter && (
+          <Select value={selectedSession} onValueChange={onSessionChange}>
+            <SelectTrigger className="flex-1 max-w-[350px] text-xs">
+              <SelectValue placeholder="All sessions" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="__all__">All sessions</SelectItem>
+              {sessions.map((s) => (
+                <SelectItem key={s} value={s}>
+                  {truncateSessionId(s)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        )}
         <Select value={selectedModel} onValueChange={onModelChange}>
           <SelectTrigger className="flex-1 max-w-[250px] text-xs">
             <SelectValue placeholder="All models" />
@@ -316,11 +467,36 @@ export function ProxyViewer({
       {/* Log list */}
       <div>
         {logs.length === 0 ? (
-          <div className="text-center text-muted-foreground py-16 space-y-4">
-            <p className="text-sm">No requests captured yet.</p>
-            <p className="text-xs">Route AI coding tools through the proxy:</p>
-            <CopyableCommand command="LLM_BASE_URL=http://localhost:25947/proxy <your-tool>" />
-          </div>
+          selectedSession !== "__all__" ? (
+            <div className="text-center text-muted-foreground py-16 space-y-4">
+              <p className="text-sm font-medium">Session not found</p>
+              <p className="text-xs font-mono bg-muted px-3 py-1 rounded inline-block max-w-[500px] break-all">
+                {truncateSessionId(selectedSession)}
+              </p>
+              <p className="text-xs">
+                This session may have been cleared or never existed.{" "}
+                {hideSessionFilter ? (
+                  <a href="/" className="underline hover:text-foreground transition-colors">
+                    Back to all sessions
+                  </a>
+                ) : (
+                  <button
+                    type="button"
+                    onClick={() => onSessionChange("__all__")}
+                    className="underline hover:text-foreground transition-colors"
+                  >
+                    Show all sessions
+                  </button>
+                )}
+              </p>
+            </div>
+          ) : (
+            <div className="text-center text-muted-foreground py-16 space-y-4">
+              <p className="text-sm">No requests captured yet.</p>
+              <p className="text-xs">Route AI coding tools through the proxy:</p>
+              <CopyableCommand command="LLM_BASE_URL=http://localhost:25947/proxy <your-tool>" />
+            </div>
+          )
         ) : (
           <div
             ref={logListWrapperRef}

package/src/components/ProxyViewerContainer.tsx

@@ -62,12 +62,32 @@ function filterLogs(
 
 const DEBOUNCE_MS = 50;
 
-export function ProxyViewerContainer(): JSX.Element {
+function buildLogsStreamUrl(sessionId: string | undefined): string {
+  if (sessionId === undefined) return "/api/logs/stream";
+  const params = new URLSearchParams({ sessionId });
+  return `/api/logs/stream?${params.toString()}`;
+}
+
+export function ProxyViewerContainer({
+  initialSessionId,
+}: {
+  /**
+   * Initial session filter. When the route is `/session/$id`, pass the URL
+   * param here so the page opens already scoped to that session. Default
+   * `__all__` keeps the existing "all sessions" behavior on `/`.
+   *
+   * NOTE: the value is only used as the initial state on mount. To pick up
+   * a new value (e.g. user navigates to a different `/session/$id`), the
+   * caller should also pass a `key` prop matching the session id, which
+   * forces a remount.
+   */
+  initialSessionId?: string;
+} = {}): JSX.Element {
   // `allLogs` is the unfiltered set populated by the SSE. The single SSE
   // connection never re-opens on filter change — we always carry the full
   // set and derive the displayed view with `useMemo` below.
   const [allLogs, setAllLogs] = useState<CapturedLog[]>([]);
-  const [selectedSession, setSelectedSession] = useState("__all__");
+  const [selectedSession, setSelectedSession] = useState(initialSessionId ?? "__all__");
   const [selectedModel, setSelectedModel] = useState("__all__");
   const [viewMode, setViewMode] = useState<"simple" | "full">("simple");
   const [error, setError] = useState<string | null>(null);
@@ -128,12 +148,7 @@ export function ProxyViewerContainer(): JSX.Element {
       eventSourceRef.current.close();
     }
 
-    // Stable, unfiltered connection. The frontend derives filtered views
-    // from the complete set, so the SSE never needs to reopen on filter
-    // change. If the in-memory set ever grows past what the client can
-    // handle, swap this back to a parameterized URL and reconnect on
-    // filter change.
-    const es = new EventSource("/api/logs/stream");
+    const es = new EventSource(buildLogsStreamUrl(initialSessionId));
     eventSourceRef.current = es;
 
     es.onmessage = (event: MessageEvent) => {
@@ -179,7 +194,7 @@ export function ProxyViewerContainer(): JSX.Element {
       }
       reconnectTimeoutRef.current = setTimeout(connectSSE, 3000);
     };
-  }, [scheduleUpdate]);
+  }, [initialSessionId, scheduleUpdate]);
 
   useEffect(() => {
     connectSSE();
@@ -200,9 +215,22 @@ export function ProxyViewerContainer(): JSX.Element {
   }, [connectSSE]);
 
   const handleClearAll = useCallback(() => {
+    if (initialSessionId !== undefined && allLogs.length === 0) return;
     void (async () => {
       try {
-        const res = await fetch("/api/logs", { method: "DELETE" });
+        const body =
+          initialSessionId === undefined
+            ? undefined
+            : JSON.stringify({ ids: allLogs.map((log) => log.id) });
+        const res = await fetch("/api/logs", {
+          method: "DELETE",
+          ...(body === undefined
+            ? {}
+            : {
+                headers: { "Content-Type": "application/json" },
+                body,
+              }),
+        });
         if (!res.ok) {
           setError("Failed to clear logs");
           return;
@@ -214,7 +242,7 @@ export function ProxyViewerContainer(): JSX.Element {
         setError(err instanceof Error ? err.message : "Unknown error clearing logs");
       }
     })();
-  }, []);
+  }, [allLogs, initialSessionId]);
 
   const handleClearGroup = useCallback((ids: number[]) => {
     if (ids.length === 0) return;
@@ -274,6 +302,9 @@ export function ProxyViewerContainer(): JSX.Element {
         onViewModeChange={setViewMode}
         strip={strip}
         slowResponseThresholdSeconds={slowResponseThresholdSeconds}
+        // Session filter is the URL's job when `initialSessionId` was given.
+        hideSessionFilter={initialSessionId !== undefined}
+        pinnedSessionId={initialSessionId}
       />
     </>
   );

package/src/components/proxy-viewer/ConversationGroup.tsx

@@ -65,18 +65,11 @@ export const ConversationGroup = memo(function ({
 
   // Pre-compute stop reasons for each log — used by turnIndices
   const turnGroups = useMemo(() => buildTurnGroups(group.logs), [group.logs]);
-  const displayId =
-    group.conversationId.startsWith("PID:") || group.conversationId.includes("|")
-      ? group.conversationId
-      : group.conversationId.length > 24
-        ? group.conversationId.slice(0, 12) + "…" + group.conversationId.slice(-12)
-        : group.conversationId;
-
   return (
     <div className="mb-2">
       {!standalone && (
         <ConversationHeader
-          conversationId={displayId}
+          conversationId={group.conversationId}
           startTime={startTime}
           endTime={endTime}
           totalCalls={group.logs.length}

package/src/components/proxy-viewer/ConversationHeader.tsx

@@ -1,8 +1,9 @@
-import { useState } from "react";
+import { useCallback, useState } from "react";
 import {
   ChevronDown,
   ChevronRight,
   Clock,
+  ExternalLink,
   Loader2,
   MessageSquare,
   Trash2,
@@ -10,6 +11,7 @@ import {
   Zap,
 } from "lucide-react";
 import type { JSX } from "react";
+import { getSessionPath } from "../../lib/sessionUrl";
 import { cn, formatTokens } from "../../lib/utils";
 import type { CapturedLog } from "../../proxy/schemas";
 import { Badge } from "../ui/badge";
@@ -34,7 +36,7 @@ export type ConversationHeaderProps = {
   expanded: boolean;
   onToggle: () => void;
   /** Hide the API format badge on the header (used when the group contains
-   * mixed formats — the per-log badges are shown instead). */
+   * mixed formats - the per-log badges are shown instead). */
   hideApiFormat?: boolean;
   /** When true and the group is collapsed, show a spinner instead of the
    * expand chevron to indicate an in-flight request inside the group. */
@@ -74,6 +76,14 @@ export function ConversationHeader({
     setConfirmOpen(true);
   };
 
+  const handleOpenInNewTab = useCallback(
+    (e: React.MouseEvent | React.KeyboardEvent): void => {
+      e.stopPropagation();
+      window.open(getSessionPath(conversationId), "_blank", "noopener,noreferrer");
+    },
+    [conversationId],
+  );
+
   return (
     <div
       role="button"
@@ -96,7 +106,7 @@ export function ConversationHeader({
         }
       }}
     >
-      {/* Expand chevron — shows spinner when collapsed and group has pending logs */}
+      {/* Expand chevron - shows spinner when collapsed and group has pending logs */}
       {expanded ? (
         <ChevronDown className="size-4 text-muted-foreground shrink-0" />
       ) : isLoading ? (
@@ -110,9 +120,11 @@ export function ConversationHeader({
         className="text-purple-400/90 font-mono text-xs font-semibold shrink-0"
         title={conversationId}
       >
-        {conversationId.length > 24
-          ? conversationId.slice(0, 12) + "…" + conversationId.slice(-12)
-          : conversationId}
+        {conversationId.startsWith("PID:") || conversationId.includes("|")
+          ? conversationId
+          : conversationId.length > 24
+            ? conversationId.slice(0, 12) + "..." + conversationId.slice(-12)
+            : conversationId}
       </span>
 
       {/* User-Agent */}
@@ -170,7 +182,23 @@ export function ConversationHeader({
       {/* Spacer */}
       <span className="flex-1 min-w-0" />
 
-      {/* Per-group Clear — does not toggle the group's expand state */}
+      {/* Open this session in a new tab - deep link to /session/$id */}
+      <button
+        type="button"
+        onClick={handleOpenInNewTab}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            handleOpenInNewTab(e);
+          }
+        }}
+        aria-label={`Open session ${conversationId} in a new tab`}
+        title="Open this session in a new tab"
+        className="text-muted-foreground hover:text-foreground transition-colors shrink-0 inline-flex items-center justify-center size-8 rounded hover:bg-muted cursor-pointer"
+      >
+        <ExternalLink className="size-3.5" />
+      </button>
+
+      {/* Per-group Clear - does not toggle the group's expand state */}
       {onClear !== undefined && (
         <button
           type="button"

package/src/components/ui/mcp-logo.tsx

@@ -0,0 +1,20 @@
+import type { JSX } from "react";
+import { cn } from "../../lib/utils";
+import McpLogoPng from "../../assets/logos/mcp.png";
+
+/**
+ * Official Model Context Protocol logo (from Wikimedia Commons). The PNG
+ * is a black-on-white raster of the official mark — flipped to a white
+ * silhouette on the dark header via `invert` so it reads against the
+ * app background.
+ */
+export function McpLogo({ className }: { className?: string }): JSX.Element {
+  return (
+    <img
+      src={McpLogoPng}
+      alt="Model Context Protocol"
+      aria-hidden="true"
+      className={cn("inline-block size-8 object-contain invert", className)}
+    />
+  );
+}

package/src/lib/sessionUrl.ts

@@ -0,0 +1,44 @@
+const B64URL_RE = /^[A-Za-z0-9_-]+$/;
+
+function bytesToBinary(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return binary;
+}
+
+function binaryToBytes(binary: string): Uint8Array {
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export function encodeSessionIdForPath(sessionId: string): string {
+  const bytes = new TextEncoder().encode(sessionId);
+  const base64 = btoa(bytesToBinary(bytes));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function decodeSessionIdFromPath(encoded: string): string {
+  if (encoded.startsWith("%")) {
+    return decodeURIComponent(encoded);
+  }
+  if (!B64URL_RE.test(encoded)) {
+    return encoded;
+  }
+  try {
+    const padded = encoded.padEnd(Math.ceil(encoded.length / 4) * 4, "=");
+    const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64);
+    return new TextDecoder().decode(binaryToBytes(binary));
+  } catch {
+    return encoded;
+  }
+}
+
+export function getSessionPath(sessionId: string): string {
+  return `/session/${encodeSessionIdForPath(sessionId)}`;
+}