@pi-unipi/unipi 2.10.2 → 2.11.0

package/packages/trajectory/src/capture.ts

@@ -1,83 +1,203 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PrefixIntegrityTracker } from "./prefix-integrity.js";
 import { TelemetrySidecar } from "./telemetry.js";
+import type { UnipiTraceRecorder } from "./tracer.js";
 
 interface RequestState {
   id: number;
-  startedAt: number;
+  turnIndex?: number;
+  startedAt?: number;
   firstTokenAt?: number;
 }
 
+interface PendingAgent {
+  runId: number;
+}
+
 /** Register read-only observability hooks. Returned reader follows the active session. */
-export function registerTelemetryCapture(pi: ExtensionAPI): () => ReturnType<TelemetrySidecar["read"]> {
+export function registerTelemetryCapture(
+  pi: ExtensionAPI,
+  sidecarRoot?: string,
+  traceRecorder?: UnipiTraceRecorder,
+): () => ReturnType<TelemetrySidecar["read"]> {
   let sidecar: TelemetrySidecar | null = null;
   let requestSeq = 0;
+  let runSeq = 0;
   let active: RequestState | null = null;
+  let lastRequestId: number | null = null;
+  let currentTurnIndex: number | undefined;
+  let pendingAgent: PendingAgent | null = null;
+  let previousTraceCursor = 0;
+  const prefixIntegrity = new PrefixIntegrityTracker();
   const toolStarts = new Map<string, number>();
 
   const bind = (ctx: ExtensionContext) => {
-    sidecar = new TelemetrySidecar(ctx.sessionManager.getSessionId());
+    const sessionId = ctx.sessionManager.getSessionId();
+    sidecar = new TelemetrySidecar(sessionId, sidecarRoot);
+    traceRecorder?.bind(sessionId);
+    const existing = sidecar.read();
+    requestSeq = Math.max(0, ...existing.flatMap(event => typeof event.requestId === "number" ? [event.requestId] : []));
+    runSeq = Math.max(0, ...existing.flatMap(event => typeof event.runId === "number" ? [event.runId] : []));
     active = null;
+    lastRequestId = null;
+    currentTurnIndex = undefined;
+    pendingAgent = null;
+    previousTraceCursor = traceRecorder?.cursor() ?? 0;
+    prefixIntegrity.reset();
     toolStarts.clear();
   };
-  const append = (type: Parameters<TelemetrySidecar["append"]>[0]["type"], data?: unknown, extra: Record<string, unknown> = {}) => {
-    sidecar?.append({ type, at: Date.now(), ...extra, ...(data === undefined ? {} : { data }) });
+  const append = (
+    type: Parameters<TelemetrySidecar["append"]>[0]["type"],
+    data?: unknown,
+    extra: Record<string, unknown> = {},
+    at = Date.now(),
+  ) => {
+    sidecar?.append({ type, at, ...extra, ...(data === undefined ? {} : { data }) });
   };
 
+  const ensureRequest = (startedAt?: number) => {
+    if (!active) {
+      active = { id: ++requestSeq, turnIndex: currentTurnIndex, startedAt };
+    } else if (startedAt !== undefined) {
+      active.startedAt = startedAt;
+    }
+    lastRequestId = active.id;
+    return active;
+  };
+  const requestExtra = (request = active) => ({
+    ...(request?.id !== undefined ? { requestId: request.id } : lastRequestId === null ? {} : { requestId: lastRequestId }),
+    ...(request?.turnIndex !== undefined ? { turnIndex: request.turnIndex } : currentTurnIndex === undefined ? {} : { turnIndex: currentTurnIndex }),
+  });
+
+
   pi.on("session_start", (_event, ctx) => { bind(ctx); });
+  pi.on("resources_discover", () => {});
+  pi.on("session_info_changed", () => {});
+  pi.on("session_before_switch", () => {});
+  pi.on("session_before_fork", () => {});
+  pi.on("session_before_compact", () => {});
+  pi.on("session_compact", (event) => { prefixIntegrity.markBoundary(`session_compact:${event.reason}`); });
+  pi.on("session_before_tree", () => {});
+  pi.on("session_tree", () => { prefixIntegrity.markBoundary("session_tree"); });
+  pi.on("session_shutdown", () => {});
+
+  pi.on("before_agent_start", (event) => {
+    pendingAgent = { runId: ++runSeq };
+  });
+  pi.on("agent_start", (event, ctx) => {
+    active = null;
+    lastRequestId = null;
+    currentTurnIndex = undefined;
+    const runId = pendingAgent?.runId ?? ++runSeq;
+    append("system-prompt", {
+      systemPrompt: ctx.getSystemPrompt(),
+      provider: ctx.model?.provider,
+      model: ctx.model?.id,
+      thinkingLevel: ctx.thinkingLevel,
+    }, { runId });
+  });
+  pi.on("agent_end", () => {});
+  pi.on("agent_settled", () => { pendingAgent = null; });
+  pi.on("turn_start", (event) => {
+    currentTurnIndex = event.turnIndex;
+    active = {
+      id: ++requestSeq,
+      turnIndex: event.turnIndex,
+    };
+    lastRequestId = active.id;
+  });
+  pi.on("turn_end", () => {});
+
+  pi.on("context", () => { ensureRequest(); });
+  pi.on("before_provider_headers", () => { ensureRequest(); });
   pi.on("before_provider_request", (event, ctx) => {
     const startedAt = Date.now();
-    active = { id: ++requestSeq, startedAt };
+    const request = ensureRequest(startedAt);
+    const integrity = prefixIntegrity.observe(event.payload, {
+      provider: ctx.model?.provider,
+      model: ctx.model?.id,
+      api: ctx.model?.api,
+      thinkingLevel: ctx.thinkingLevel,
+    });
+    const traceCursor = traceRecorder?.cursor() ?? 0;
+    const contributingTrace = traceRecorder?.since(previousTraceCursor) ?? [];
+    previousTraceCursor = traceCursor;
+    const attributed = integrity.verdict === "violation"
+      ? contributingTrace
+          .filter(item => item.type === "unipi-trace")
+          .map(item => item.data)
+          .filter((data): data is Record<string, unknown> => Boolean(data && typeof data === "object"))
+          .filter(data => data.phase === "exit" && (
+            data.surface === "hook" && data.mutation && (data.mutation as Record<string, unknown>).changed === true ||
+            data.surface === "api" && ["sendMessage", "sendUserMessage", "setActiveTools", "setModel", "setThinkingLevel", "registerProvider", "unregisterProvider"].includes(String(data.action)) ||
+            data.surface === "context-api" && ["compact", "navigateTree", "switchSession", "newSession", "fork", "reload"].includes(String(data.action))
+          ))
+          .slice(-20)
+      : [];
+    append("prefix-integrity", {
+      ...integrity,
+      attribution: attributed.length > 0 ? attributed : undefined,
+    }, requestExtra(request));
     append("request", {
       payload: event.payload,
       provider: ctx.model?.provider,
       model: ctx.model?.id,
       thinkingLevel: ctx.thinkingLevel,
-      tools: Array.isArray((event.payload as { tools?: unknown })?.tools)
-        ? (event.payload as { tools: unknown }).tools
-        : undefined,
-    }, { requestId: active.id });
-  });
-  pi.on("after_provider_response", (event) => {
-    append("response", { status: event.status, headers: event.headers }, active ? { requestId: active.id } : {});
+    }, requestExtra(request));
   });
+  pi.on("after_provider_response", () => {});
+
+  pi.on("message_start", () => {});
   pi.on("message_update", (event) => {
-    if (!active || active.firstTokenAt !== undefined) return;
+    const request = ensureRequest();
+    if (request.firstTokenAt !== undefined) return;
     if (!["text_delta", "thinking_delta", "toolcall_delta"].includes(event.assistantMessageEvent.type)) return;
-    active.firstTokenAt = Date.now();
-    append("first-token", {
-      ttftMs: active.firstTokenAt - active.startedAt,
-      eventType: event.assistantMessageEvent.type,
-    }, { requestId: active.id });
+    request.firstTokenAt = Date.now();
+
   });
   pi.on("message_end", (event) => {
     if (event.message.role !== "assistant" || !active) return;
     const completedAt = Date.now();
     append("message-end", {
-      totalMs: completedAt - active.startedAt,
-      ttftMs: active.firstTokenAt === undefined ? undefined : active.firstTokenAt - active.startedAt,
+      totalMs: active.startedAt === undefined ? undefined : completedAt - active.startedAt,
+      ttftMs: active.startedAt === undefined || active.firstTokenAt === undefined
+        ? undefined
+        : active.firstTokenAt - active.startedAt,
       decodingMs: active.firstTokenAt === undefined ? undefined : completedAt - active.firstTokenAt,
       usage: event.message.usage,
       stopReason: event.message.stopReason,
       errorMessage: event.message.errorMessage,
-    }, { requestId: active.id });
+    }, requestExtra());
     active = null;
   });
-  pi.on("tool_execution_start", (event) => {
-    const at = Date.now();
-    toolStarts.set(event.toolCallId, at);
-    append("tool-start", { toolName: event.toolName, args: event.args }, { toolCallId: event.toolCallId });
-  });
+
+  pi.on("tool_execution_start", (event) => { toolStarts.set(event.toolCallId, Date.now()); });
+  pi.on("tool_call", () => {});
+  pi.on("tool_execution_update", () => {});
+  pi.on("tool_result", () => {});
   pi.on("tool_execution_end", (event) => {
     const at = Date.now();
     const startedAt = toolStarts.get(event.toolCallId);
     append("tool-end", {
       toolName: event.toolName,
-      result: event.result,
       isError: event.isError,
       durationMs: startedAt === undefined ? undefined : at - startedAt,
-    }, { toolCallId: event.toolCallId });
+    }, { ...requestExtra(), toolCallId: event.toolCallId });
     toolStarts.delete(event.toolCallId);
   });
 
-  return () => sidecar?.read() ?? [];
+  pi.on("model_select", (event) => {
+    if (event.previousModel && (
+      event.previousModel.provider !== event.model.provider ||
+      event.previousModel.id !== event.model.id ||
+      event.previousModel.api !== event.model.api
+    )) prefixIntegrity.markBoundary("model_select");
+  });
+  pi.on("thinking_level_select", (event) => {
+    if (event.previousLevel !== event.level) prefixIntegrity.markBoundary("thinking_level_select");
+  });
+  pi.on("user_bash", () => {});
+  pi.on("input", () => {});
+
+  return () => sidecar?.read() ?? traceRecorder?.read() ?? [];
 }

package/packages/trajectory/src/prefix-integrity.ts

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+
+export type PrefixVerdict = "first_request" | "identical_retry" | "prefix_extended" | "boundary" | "violation";
+
+export interface PrefixDifference {
+  surface: "messages" | "system" | "tools" | "envelope" | "shape";
+  kind: "changed" | "inserted" | "removed" | "reordered";
+  path: string;
+  index?: number;
+  beforeFingerprint?: string;
+  afterFingerprint?: string;
+}
+
+export interface PrefixIntegrityResult {
+  epoch: number;
+  verdict: PrefixVerdict;
+  messageField: string;
+  previousItems: number;
+  currentItems: number;
+  extendedBy: number;
+  requestFingerprint: string;
+  messagesFingerprint: string;
+  systemFingerprint: string;
+  toolsFingerprint: string;
+  envelopeFingerprint: string;
+  boundaryReason?: string;
+  differences: PrefixDifference[];
+}
+
+interface RequestState {
+  requestFingerprint: string;
+  messageField: string;
+  messages: unknown[];
+  messageFingerprints: string[];
+  systemFingerprint: string;
+  toolsFingerprint: string;
+  envelopeFingerprint: string;
+}
+
+function canonicalize(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (value === undefined) return { $type: "undefined" };
+  if (typeof value === "bigint") return { $type: "bigint", value: value.toString() };
+  if (typeof value === "number" && !Number.isFinite(value)) return { $type: "number", value: String(value) };
+  if (typeof value !== "object" || value === null) return value;
+  if (seen.has(value)) return { $type: "cycle" };
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value.map(item => canonicalize(item, seen));
+    seen.delete(value);
+    return result;
+  }
+  if (value instanceof Uint8Array) {
+    seen.delete(value);
+    return { $type: "bytes", length: value.byteLength };
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    result[key] = canonicalize((value as Record<string, unknown>)[key], seen);
+  }
+  seen.delete(value);
+  return result;
+}
+
+function fingerprint(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex").slice(0, 16);
+}
+
+function payloadObject(payload: unknown): Record<string, unknown> {
+  return payload && typeof payload === "object" && !Array.isArray(payload)
+    ? payload as Record<string, unknown>
+    : { payload };
+}
+
+function messageSequence(payload: Record<string, unknown>): { field: string; items: unknown[] } {
+  for (const field of ["messages", "input", "contents"] as const) {
+    if (Array.isArray(payload[field])) return { field, items: payload[field] as unknown[] };
+  }
+  return { field: "none", items: [] };
+}
+
+function systemSurface(payload: Record<string, unknown>, field: string, messages: unknown[]): unknown {
+  const direct = Object.fromEntries(Object.entries(payload).filter(([key]) => /^(system|instructions|developer)/i.test(key)));
+  const leading = field === "messages"
+    ? messages.filter((message) => {
+      if (!message || typeof message !== "object") return false;
+      const role = (message as Record<string, unknown>).role;
+      return role === "system" || role === "developer";
+    })
+    : [];
+  return { direct, leading };
+}
+
+function toolsSurface(payload: Record<string, unknown>): unknown {
+  return { tools: payload.tools, toolChoice: payload.tool_choice ?? payload.toolChoice };
+}
+
+function envelopeSurface(payload: Record<string, unknown>, sequenceField: string): unknown {
+  const omitted = new Set([sequenceField, "tools", "tool_choice", "toolChoice"]);
+  return Object.fromEntries(Object.entries(payload).filter(([key]) => !omitted.has(key) && !/^(system|instructions|developer)/i.test(key)));
+}
+
+function state(payload: unknown, route?: unknown): RequestState {
+  const object = payloadObject(payload);
+  const sequence = messageSequence(object);
+  const system = systemSurface(object, sequence.field, sequence.items);
+  const tools = toolsSurface(object);
+  const envelope = { route, payload: envelopeSurface(object, sequence.field) };
+  return {
+    requestFingerprint: fingerprint({ route, payload: object }),
+    messageField: sequence.field,
+    messages: sequence.items,
+    messageFingerprints: sequence.items.map(fingerprint),
+    systemFingerprint: fingerprint(system),
+    toolsFingerprint: fingerprint(tools),
+    envelopeFingerprint: fingerprint(envelope),
+  };
+}
+
+function messageDifference(previous: RequestState, current: RequestState): PrefixDifference | undefined {
+  if (previous.messageField !== current.messageField) {
+    return { surface: "shape", kind: "changed", path: "$.messageField", beforeFingerprint: fingerprint(previous.messageField), afterFingerprint: fingerprint(current.messageField) };
+  }
+  const limit = Math.min(previous.messageFingerprints.length, current.messageFingerprints.length);
+  for (let index = 0; index < limit; index++) {
+    if (previous.messageFingerprints[index] === current.messageFingerprints[index]) continue;
+    const laterIndex = current.messageFingerprints.indexOf(previous.messageFingerprints[index]!, index + 1);
+    const earlierIndex = previous.messageFingerprints.indexOf(current.messageFingerprints[index]!, index + 1);
+    return {
+      surface: "messages",
+      kind: laterIndex >= 0 || earlierIndex >= 0 ? "reordered" : "changed",
+      path: `$.${current.messageField}[${index}]`, index,
+      beforeFingerprint: previous.messageFingerprints[index], afterFingerprint: current.messageFingerprints[index],
+    };
+  }
+  if (current.messageFingerprints.length < previous.messageFingerprints.length) {
+    const index = current.messageFingerprints.length;
+    return { surface: "messages", kind: "removed", path: `$.${current.messageField}[${index}]`, index, beforeFingerprint: previous.messageFingerprints[index] };
+  }
+  return undefined;
+}
+
+export class PrefixIntegrityTracker {
+  private epoch = 0;
+  private previous: RequestState | null = null;
+  private boundaryReason: string | undefined;
+
+  reset(): void {
+    this.epoch = 0;
+    this.previous = null;
+    this.boundaryReason = undefined;
+  }
+
+  markBoundary(reason: string): void {
+    if (this.previous) this.epoch++;
+    this.previous = null;
+    this.boundaryReason = reason;
+  }
+
+  observe(payload: unknown, route?: unknown): PrefixIntegrityResult {
+    const current = state(payload, route);
+    const boundaryReason = this.boundaryReason;
+    if (!this.previous) {
+      if (this.epoch === 0) this.epoch = 1;
+      this.previous = current;
+      this.boundaryReason = undefined;
+      return {
+        epoch: this.epoch,
+        verdict: boundaryReason ? "boundary" : "first_request",
+        messageField: current.messageField,
+        previousItems: 0,
+        currentItems: current.messages.length,
+        extendedBy: current.messages.length,
+        requestFingerprint: current.requestFingerprint,
+        messagesFingerprint: fingerprint(current.messageFingerprints),
+        systemFingerprint: current.systemFingerprint,
+        toolsFingerprint: current.toolsFingerprint,
+        envelopeFingerprint: current.envelopeFingerprint,
+        ...(boundaryReason ? { boundaryReason } : {}),
+        differences: [],
+      };
+    }
+
+    const previous = this.previous;
+    const differences: PrefixDifference[] = [];
+    const messageDiff = messageDifference(previous, current);
+    if (messageDiff) differences.push(messageDiff);
+    if (previous.systemFingerprint !== current.systemFingerprint) differences.push({ surface: "system", kind: "changed", path: "$.system", beforeFingerprint: previous.systemFingerprint, afterFingerprint: current.systemFingerprint });
+    if (previous.toolsFingerprint !== current.toolsFingerprint) differences.push({ surface: "tools", kind: "changed", path: "$.tools", beforeFingerprint: previous.toolsFingerprint, afterFingerprint: current.toolsFingerprint });
+    if (previous.envelopeFingerprint !== current.envelopeFingerprint) differences.push({ surface: "envelope", kind: "changed", path: "$.envelope", beforeFingerprint: previous.envelopeFingerprint, afterFingerprint: current.envelopeFingerprint });
+
+    const verdict: PrefixVerdict = current.requestFingerprint === previous.requestFingerprint
+      ? "identical_retry"
+      : differences.length === 0
+        ? "prefix_extended"
+        : "violation";
+    const result: PrefixIntegrityResult = {
+      epoch: this.epoch,
+      verdict,
+      messageField: current.messageField,
+      previousItems: previous.messages.length,
+      currentItems: current.messages.length,
+      extendedBy: Math.max(0, current.messages.length - previous.messages.length),
+      requestFingerprint: current.requestFingerprint,
+      messagesFingerprint: fingerprint(current.messageFingerprints),
+      systemFingerprint: current.systemFingerprint,
+      toolsFingerprint: current.toolsFingerprint,
+      envelopeFingerprint: current.envelopeFingerprint,
+      differences,
+    };
+    this.previous = current;
+    return result;
+  }
+}

package/packages/trajectory/src/project.ts

@@ -1,7 +1,7 @@
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { TelemetryEvent } from "./telemetry.js";
 
-export type TrajectoryKind = "system" | "user" | "assistant" | "tool" | "compaction" | "branch";
+export type TrajectoryKind = "system" | "unipi" | "prefix" | "user" | "assistant" | "tool" | "compaction" | "branch";
 
 export interface TrajectoryUsage {
   input?: number;
@@ -38,6 +38,13 @@ export interface TrajectoryRecord {
   request?: unknown;
   response?: unknown;
   tools?: unknown;
+  data?: unknown;
+  package?: string;
+  surface?: string;
+  phase?: string;
+  verdict?: string;
+  epoch?: number;
+  attribution?: unknown;
 }
 
 export interface TrajectorySnapshot {
@@ -165,12 +172,56 @@ export function projectTrajectory(
     }
   }
 
+  const firstEntryAt = records[0]?.timestamp ?? Date.now();
+  let syntheticSeq = -telemetry.length;
+  for (const event of telemetry) {
+    if (!["system-prompt", "unipi-trace", "prefix-integrity"].includes(event.type)) continue;
+    const data = event.data as AnyRecord | undefined;
+    // Package traces are attribution evidence, not a second activity log. Only
+    // operations that changed a provider-visible surface belong in trajectory.
+    if (event.type === "unipi-trace" && data?.affectsContext !== true) continue;
+    const traceAction = String(data?.hook ?? data?.action ?? data?.channel ?? data?.surface ?? "operation");
+    const kind: TrajectoryKind = event.type === "system-prompt" ? "system" : event.type === "unipi-trace" ? "unipi" : "prefix";
+    const title = event.type === "system-prompt"
+      ? "SYSTEM PROMPT"
+      : event.type === "unipi-trace"
+        ? `${String(data?.package ?? "unipi")} · ${traceAction}`
+        : `PREFIX · ${String(data?.verdict ?? "unknown")}`;
+    const value = event.type === "system-prompt" ? data?.systemPrompt : data;
+    records.push({
+      id: `telemetry:${event.type}:${event.at}:${syntheticSeq}`,
+      seq: syntheticSeq++,
+      turn: event.turnIndex === undefined ? null : event.turnIndex + 1,
+      step: null,
+      kind,
+      timestamp: event.at || firstEntryAt,
+      durationMs: typeof data?.durationMs === "number" ? data.durationMs : null,
+      title,
+      preview: event.type === "prefix-integrity"
+        ? `${String(data?.verdict ?? "unknown")} · epoch ${String(data?.epoch ?? "?")}${Array.isArray(data?.differences) && data.differences[0] ? ` · ${String(data.differences[0].path ?? data.differences[0].surface ?? "changed")}` : ""}`
+        : preview(event.type === "system-prompt" ? value : JSON.stringify(value ?? {})),
+      output: event.type === "system-prompt" ? value : undefined,
+      data,
+      package: typeof data?.package === "string" ? data.package : undefined,
+      surface: typeof data?.surface === "string" ? data.surface : undefined,
+      phase: typeof data?.phase === "string" ? data.phase : undefined,
+      verdict: typeof data?.verdict === "string" ? data.verdict : undefined,
+      epoch: typeof data?.epoch === "number" ? data.epoch : undefined,
+      attribution: data?.attribution,
+      isError: data?.phase === "error" || data?.verdict === "violation",
+      request: event.requestId === undefined ? undefined : { requestId: event.requestId },
+    });
+  }
+  records.sort((a, b) => a.timestamp - b.timestamp || a.seq - b.seq);
+
   const assistantRecords = records.filter(record => record.kind === "assistant");
-  const requestIds = [...new Set(telemetry.flatMap(event => event.requestId === undefined ? [] : [event.requestId]))];
-  for (const [index, requestId] of requestIds.entries()) {
-    const record = assistantRecords[index];
-    if (!record) break;
+  const requestIds = [...new Set(telemetry.flatMap(event => event.type === "request" && event.requestId !== undefined ? [event.requestId] : []))];
+  for (const requestId of requestIds) {
     const events = telemetry.filter(event => event.requestId === requestId);
+    const requestAt = events.find(event => event.type === "request")?.at ?? 0;
+    const record = assistantRecords.find(candidate => candidate.request === undefined && candidate.timestamp >= requestAt)
+      ?? assistantRecords.find(candidate => candidate.request === undefined);
+    if (!record) break;
     const request = events.find(event => event.type === "request")?.data as AnyRecord | undefined;
     const response = events.find(event => event.type === "response")?.data;
     const end = events.find(event => event.type === "message-end")?.data as AnyRecord | undefined;
@@ -188,6 +239,7 @@ export function projectTrajectory(
     const end = telemetry.find(event => event.type === "tool-end" && event.toolCallId === record.toolCallId)?.data as AnyRecord | undefined;
     if (typeof end?.durationMs === "number") record.durationMs = end.durationMs;
   }
+  records.forEach((record, index) => { record.seq = index; });
 
   return { ...meta, generatedAt: Date.now(), records };
 }

package/packages/trajectory/src/server.ts

@@ -11,10 +11,17 @@ export interface TrajectoryServerOptions {
 
 const HOST = "127.0.0.1";
 
-function json(res: ServerResponse, value: unknown): void {
+function json(res: ServerResponse, value: TrajectorySnapshot, requestEtag?: string): void {
+  const etag = `W/\"${value.sessionId}:${value.generatedAt}\"`;
+  if (requestEtag === etag) {
+    res.writeHead(304, { ETag: etag });
+    res.end();
+    return;
+  }
   res.writeHead(200, {
-    "Cache-Control": "no-store",
+    "Cache-Control": "no-cache",
     "Content-Type": "application/json; charset=utf-8",
+    ETag: etag,
     "X-Content-Type-Options": "nosniff",
   });
   res.end(JSON.stringify(value));
@@ -35,7 +42,7 @@ export class TrajectoryServer {
       try {
         const url = new URL(req.url ?? "/", `http://${HOST}`);
         if (req.method !== "GET") { res.writeHead(405).end("Method Not Allowed"); return; }
-        if (url.pathname === "/api/snapshot") { json(res, this.options.snapshot()); return; }
+        if (url.pathname === "/api/snapshot") { json(res, this.options.snapshot(), req.headers["if-none-match"]); return; }
         if (url.pathname === "/favicon.ico") { res.writeHead(204).end(); return; }
         if (url.pathname === "/app.js") {
         res.writeHead(200, { "Cache-Control": "no-store", "Content-Type": "application/javascript; charset=utf-8", "X-Content-Type-Options": "nosniff" });