dsh-better-display 0.3.7 → 0.3.9

package/src/client/tool-activity.ts

@@ -2,6 +2,7 @@ import type { AssistantBlock, ToolCallBlock, TurnLocation } from '@deepseek-ai/d
 import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
 import type { ReaderGroup } from './projection.js';
+import { anchorSeqOf, cutContains, rewindCutSpans, type CutChatNode } from './rewind-cut.js';
 
 export type ToolDraft = Extract<AssistantBlock, { kind: 'tool-call' }>;
 export type ToolPhase = 'preparing' | 'running' | 'returned' | 'succeeded' | 'failed' | 'interrupted';
@@ -12,11 +13,52 @@ export interface ToolActivityEntry {
 }
 export type ReaderFlowEntry = ToolActivityEntry | { kind: 'node'; key: string; nodeKey: string; order: number };
 
-/** Public Step data includes tool-only model output before a chat node exists. */
-export function readerFlow(group: ReaderGroup, turn: TurnLocation | undefined, get: (key: string) => ChatConversationViewNode | undefined): ReaderFlowEntry[] {
+/**
+ * callId of a tool-call chat node. Drafts for a call whose node was cut must
+ * not be reintroduced after `group.keys` has already dropped that node.
+ */
+function toolCallId(node: ChatConversationViewNode): string | undefined {
+  const callId = (node.data as { root?: { callId?: unknown } } | null)?.root?.callId;
+  return typeof callId === 'string' && callId.length > 0 ? callId : undefined;
+}
+
+/** callIds whose tool-call node sits inside a rewind cut. */
+function cutToolCallIds(
+  order: readonly string[],
+  get: (key: string) => ChatConversationViewNode | undefined,
+  spans: readonly { readonly start: number; readonly end: number }[],
+): Set<string> {
+  const ids = new Set<string>();
+  for (const key of order) {
+    const node = get(key);
+    if (node?.kind !== 'tool-call') continue;
+    const seq = anchorSeqOf(node as CutChatNode);
+    if (seq === undefined || !cutContains(spans, seq)) continue;
+    const callId = toolCallId(node);
+    if (callId !== undefined) ids.add(callId);
+  }
+  return ids;
+}
+
+/**
+ * Public Step data includes tool-only model output before a chat node exists.
+ *
+ * `sourceOrder` is the unfiltered chat order. Drafts that belong to a cut step,
+ * or to a call whose tool-call node was cut, are not put back. A draft that
+ * still has no tool-call node, on a step outside the cut, stays — that is the
+ * in-flight call the host has not published a node for yet.
+ */
+export function readerFlow(
+  group: ReaderGroup,
+  turn: TurnLocation | undefined,
+  get: (key: string) => ChatConversationViewNode | undefined,
+  sourceOrder?: readonly string[],
+): ReaderFlowEntry[] {
   const flow: ReaderFlowEntry[] = [];
   const calls = new Map<string, ToolActivityEntry>();
   const assistantOrder = new Map<number, number>();
+  const spans = sourceOrder === undefined ? [] : rewindCutSpans({ order: sourceOrder, nodes: { get } });
+  const cutCalls = spans.length === 0 || sourceOrder === undefined ? undefined : cutToolCallIds(sourceOrder, get, spans);
   for (const key of group.keys) {
     const node = get(key);
     if (!node || node.visibility === 'hidden') continue;
@@ -31,10 +73,15 @@ export function readerFlow(group: ReaderGroup, turn: TurnLocation | undefined, g
   }
   for (const step of turn?.steps ?? []) {
     const data = step.data.get('assistant-step');
+    const stepSeq = step.start?.seq;
+    const stepCut = typeof stepSeq === 'number' && spans.length > 0 && cutContains(spans, stepSeq);
     let index = 0;
     for (const draft of data?.blocks ?? []) {
       if (draft.kind !== 'tool-call' || !draft.callId) continue;
       const previous = calls.get(draft.callId);
+      // A visible tool row still receives its draft. A new row is the streaming
+      // case — unless this step, or this call's tool-call node, was cut.
+      if (!previous && (stepCut || cutCalls?.has(draft.callId) === true)) continue;
       calls.set(draft.callId, previous ? { ...previous, draft } : {
         kind: 'tool', key: `reader-tool:${draft.callId}`, callId: draft.callId, step: step.step, draft,
         order: (assistantOrder.get(step.step) ?? step.start?.seq ?? 0) + .01 + index++ / 10000,
@@ -53,10 +100,15 @@ export function stringValue(record: Record<string, unknown> | null, ...keys: str
   return undefined;
 }
 
+/** Top-level fields from complete or in-flight JSON tool arguments. */
+type ParsedInputFields =
+  | { kind: 'complete'; fields: Record<string, unknown> }
+  | { kind: 'partial'; fields: Record<string, unknown> };
+
 /** Read only top-level JSON string values, including an unfinished final string.
  * This never executes input or mistakes escaped/nested content for a path field. */
-export function inputFields(raw: string): Record<string, unknown> {
-  try { return objectValue(JSON.parse(raw)) ?? {}; } catch { /* an in-flight argument is normally incomplete */ }
+function parseInputFields(raw: string): ParsedInputFields {
+  try { return { kind: 'complete', fields: objectValue(JSON.parse(raw)) ?? {} }; } catch { /* an in-flight argument is normally incomplete */ }
   const fields: Record<string, unknown> = Object.create(null);
   const prefix = raw.slice(0, 262144);
   let depth = 0;
@@ -88,14 +140,19 @@ export function inputFields(raw: string): Record<string, unknown> {
     if (closed && /^\s*:/.test(prefix.slice(index + 1))) key = value;
     else if (key !== undefined) { fields[key] = value; key = undefined; }
   }
-  return fields;
+  return { kind: 'partial', fields };
 }
 
+export function inputFields(raw: string): Record<string, unknown> {
+  return parseInputFields(raw).fields;
+}
+
+/** Name and raw arguments of any call block, whether it has landed or is pending. */
 export function toolIdentity(entry: Pick<ToolActivityEntry, 'block' | 'draft'>) {
   const block = entry.block;
   return {
     name: block ? 'kind' in block ? block.call?.name ?? entry.draft?.name ?? '工具调用' : block.name : entry.draft?.name ?? '工具调用',
-    raw: block ? 'kind' in block ? block.call?.argsRaw ?? entry.draft?.argsRaw ?? '' : ('argsRaw' in block ? block.argsRaw : '') : entry.draft?.argsRaw ?? '',
+    raw: block ? 'kind' in block ? block.call?.argsRaw ?? entry.draft?.argsRaw ?? '' : ('argsRaw' in block ? block.argsRaw : entry.draft?.argsRaw ?? '') : entry.draft?.argsRaw ?? '',
   };
 }
 
@@ -254,7 +311,7 @@ export function foldDiffHunks(steps: readonly { kind: string; entry?: ToolActivi
 
 export function activityPhase(entry: Pick<ToolActivityEntry, 'block' | 'draft'>, turnClosed = false): ToolPhase {
   if (!entry.block) return turnClosed ? 'interrupted' : 'preparing';
-  if (!('kind' in entry.block)) return turnClosed ? 'interrupted' : 'running';
+  if (!('kind' in entry.block)) return turnClosed ? 'interrupted' : entry.block.phase === 'preparing' ? 'preparing' : 'running';
   // RC1 publishes canonical cancellation as an error result with a typed code.
   if (entry.block.error?.code === 'ABORTED' || entry.block.error?.code === 'interrupted') return 'interrupted';
   const facts = executionFacts(entry.block);
@@ -308,7 +365,8 @@ export function forgetCallClock(callId: string): void {
 
 export function activitySummary(entry: Pick<ToolActivityEntry, 'block' | 'draft'>) {
   const { name, raw } = toolIdentity(entry);
-  const args = inputFields(raw);
+  const parsed = parseInputFields(raw);
+  const args = parsed.fields;
   const target = stringValue(args, 'file_path', 'path', 'filename', 'filePath');
   const command = stringValue(args, 'command', 'cmd', 'script');
   const description = stringValue(args, 'description');
@@ -331,7 +389,7 @@ export function activitySummary(entry: Pick<ToolActivityEntry, 'block' | 'draft'
     : category === 'web' ? name === 'web_search' ? '搜索网页' : '读取网页'
     : category === 'code' ? (description || '运行代码')
     : name;
-  return { name, raw, args, category, title, target: target ?? command ?? stringValue(args, 'query', 'pattern', 'url'), command,
+  return { name, raw, args, argsState: parsed.kind, category, title, target: target ?? command ?? stringValue(args, 'query', 'pattern', 'url'), command,
     cwd: stringValue(args, 'workdir', 'cwd'), content: stringValue(args, 'content', 'new_string', 'newText', 'file_text') };
 }
 

package/src/client/turn-slots.ts

@@ -0,0 +1,80 @@
+/** One turn lane: `live` while it is still in the visible order. */
+export interface TurnSlot<T extends { readonly key: string }> {
+  readonly group: T;
+  readonly live: boolean;
+}
+
+/**
+ * Keep live turns in the incoming `groups` order, and keep a departing turn
+ * next to the live neighbour that preceded it.
+ *
+ * A rewind removes turn keys from the visible order. Unmounting them in that
+ * same commit snaps the transcript, so the lane retains the last group object
+ * until the collapse finishes. A re-render, a stream tick, or a reconnect that
+ * still contains the same keys only replaces the group object and leaves
+ * `live` true — those updates must not start a collapse. A key that returns
+ * is live again where `groups` places it. Loading older history therefore
+ * stays in transcript order instead of appending the older turns after the
+ * ones already on screen. A departing slot is inserted immediately after the
+ * nearest preceding slot that is still live, or at the front when it had none,
+ * so several departing neighbours keep their relative order.
+ *
+ * Returns `current` itself when nothing changed, so a React state update can
+ * bail out on `Object.is`.
+ */
+export function reconcileTurnSlots<T extends { readonly key: string }>(
+  current: readonly TurnSlot<T>[],
+  groups: readonly T[],
+): readonly TurnSlot<T>[] {
+  const incoming = new Map(groups.map(group => [group.key, group]));
+  const next: TurnSlot<T>[] = groups.map(group => ({ group, live: true }));
+  for (const slot of current) {
+    if (incoming.has(slot.group.key)) continue;
+    insertDeparting(next, { group: slot.group, live: false }, precedingLiveKey(current, incoming, slot.group.key));
+  }
+  const same =
+    next.length === current.length &&
+    next.every(
+      (slot, index) => slot.live === current[index]!.live && slot.group === current[index]!.group,
+    );
+  return same ? current : next;
+}
+
+/** Nearest preceding slot that is still in the incoming order, if any. */
+function precedingLiveKey<T extends { readonly key: string }>(
+  current: readonly TurnSlot<T>[],
+  incoming: ReadonlyMap<string, T>,
+  key: string,
+): string | undefined {
+  const index = current.findIndex(slot => slot.group.key === key);
+  for (let cursor = index - 1; cursor >= 0; cursor--) {
+    const candidate = current[cursor]!.group.key;
+    if (incoming.has(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Place a departing slot after `anchorKey`, or at the front when the slot had
+ * no preceding live neighbour. Slots that share an anchor keep `current` order
+ * because each one is inserted at the end of the departing run after that anchor.
+ */
+function insertDeparting<T extends { readonly key: string }>(
+  next: TurnSlot<T>[],
+  slot: TurnSlot<T>,
+  anchorKey: string | undefined,
+): void {
+  if (anchorKey === undefined) {
+    const firstLive = next.findIndex(item => item.live);
+    next.splice(firstLive < 0 ? next.length : firstLive, 0, slot);
+    return;
+  }
+  const anchorIndex = next.findIndex(item => item.group.key === anchorKey);
+  if (anchorIndex < 0) {
+    next.unshift(slot);
+    return;
+  }
+  let insertAt = anchorIndex + 1;
+  while (insertAt < next.length && next[insertAt]?.live === false) insertAt++;
+  next.splice(insertAt, 0, slot);
+}

package/src/client/types.ts

@@ -10,10 +10,29 @@ import type { OfficialSeat } from './official-slots.js';
 import type { OpenFileOptions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client';
 import type {} from '@deepseek-ai/dsh-client-ui-tool/client';
 
+/**
+ * Display inputs the Reader already computed for this block.
+ * Older callers may omit the object. Registrants must tolerate that.
+ */
+export interface ReaderBlockPresentation {
+  /** Assistant step time, when the Reader has one. */
+  startedAt?: number;
+  /** True when this step was interrupted. */
+  interrupted?: boolean;
+  /** True when this block may run the live reveal. */
+  liveText?: boolean;
+}
+
 export interface ReaderBlockOwner {
   block: AssistantBlock;
   streaming: boolean;
   source: 'assistant' | 'user' | 'tool';
+  /** Viewport and motion inputs. Absent on owners built before this field existed. */
+  presentation?: ReaderBlockPresentation;
+  /** Selection is holding Markdown formatting in place. */
+  holdFormatting?: boolean;
+  /** Same value as `presentation.liveText`, repeated so a registrant can read it directly. */
+  liveText?: boolean;
 }
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {

package/src/dsh-better-display.ts

@@ -1,6 +1,9 @@
-import { spawn } from 'node:child_process';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
+import { loadFlags, type Flags } from './flags.js';
+import { createLogger, requestIdOf } from './log.js';
+import { metricsPayload, recordRouteDuration, recordRouteHit, ROUTE_METRICS, ROUTE_REVEAL, ROUTE_SKILL_STATUS } from './metrics.js';
+import { createRevealHandler, revealRoots } from './reveal.js';
 import { scanGenerativeMcpappsStatus } from './skill-roots.js';
 import { skillsFromListResult, toPublicSkillStatus } from './skill-status.js';
 
@@ -19,6 +22,8 @@ declare module '@deepseek-ai/cordis' {
 export const name = 'dsh-better-display';
 export const inject = ['webServer'];
 
+const log = createLogger({ base: { plugin: name } });
+
 function writeJson(res: ServerResponse, status: number, body: unknown): void {
   res.setHeader('Content-Type', 'application/json');
   res.statusCode = status;
@@ -31,56 +36,48 @@ function skillLister(ctx: Context): (() => Promise<readonly { readonly name?: st
   return async () => skillsFromListResult(await skills.list!({}));
 }
 
-export function apply(ctx: Context): void {
-  console.log('[my-plugins/dsh-better-display] loaded');
+function beginRequest(req: IncomingMessage, res: ServerResponse, route: string): string {
+  const requestId = requestIdOf(req);
+  res.setHeader('X-Request-ID', requestId);
+  recordRouteHit(route);
+  const started = performance.now();
+  res.on('finish', () => {
+    recordRouteDuration(route, performance.now() - started);
+  });
+  log.info('http request', {
+    requestId,
+    route,
+    method: req.method ?? '',
+    url: req.url ?? '',
+    headers: req.headers,
+  });
+  return requestId;
+}
+
+export function apply(ctx: Context, options?: { readonly flags?: Flags }): void {
+  const flags = options?.flags ?? loadFlags();
+  log.info('[my-plugins/dsh-better-display] loaded', { readerEnabled: flags.readerEnabled });
+  if (!flags.readerEnabled) {
+    log.info('route registration skipped', { readerEnabled: false });
+    return;
+  }
 
   if (ctx.webServer) {
     ctx.effect(() => {
+      const reveal = createRevealHandler({ roots: sessionId => revealRoots(ctx, sessionId) });
       const disposeReveal = ctx.webServer!.register({
         kind: 'exact',
-        path: '/better-display/reveal',
-        handler: async (req, res) => {
-          if (req.method !== 'POST') {
-            res.statusCode = 405;
-            res.end();
-            return;
-          }
-          let body = '';
-          req.on('data', chunk => { body += chunk; });
-          req.on('end', () => {
-            try {
-              const data = JSON.parse(body);
-              const targetPath = typeof data.path === 'string' ? data.path.trim() : '';
-              if (!targetPath) {
-                res.statusCode = 400;
-                res.end(JSON.stringify({ ok: false, error: 'Empty path' }));
-                return;
-              }
-
-              if (process.platform === 'darwin') {
-                // Exact file reveal in macOS Finder with selection highlight
-                spawn('open', ['-R', targetPath], { detached: true, stdio: 'ignore' });
-              } else if (process.platform === 'win32') {
-                // Exact file selection in Windows Explorer
-                spawn('explorer.exe', [`/select,${targetPath}`], { detached: true, stdio: 'ignore' });
-              } else {
-                spawn('xdg-open', [targetPath], { detached: true, stdio: 'ignore' });
-              }
-
-              res.setHeader('Content-Type', 'application/json');
-              res.statusCode = 200;
-              res.end(JSON.stringify({ ok: true }));
-            } catch (err) {
-              res.statusCode = 400;
-              res.end(JSON.stringify({ ok: false, error: String(err) }));
-            }
-          });
+        path: ROUTE_REVEAL,
+        handler: (req, res) => {
+          beginRequest(req, res, ROUTE_REVEAL);
+          reveal(req, res);
         },
       });
       const disposeSkill = ctx.webServer!.register({
         kind: 'exact',
-        path: '/better-display/skill-status',
+        path: ROUTE_SKILL_STATUS,
         handler: async (req, res) => {
+          const requestId = beginRequest(req, res, ROUTE_SKILL_STATUS);
           if (req.method !== 'GET') {
             res.statusCode = 405;
             res.end();
@@ -95,14 +92,32 @@ export function apply(ctx: Context): void {
             });
             writeJson(res, 200, toPublicSkillStatus(status));
           } catch (err) {
+            log.error('skill-status failed', {
+              requestId,
+              error: err instanceof Error ? err.message : String(err),
+            });
             writeJson(res, 500, { ok: false, error: String(err) });
           }
         },
       });
+      const disposeMetrics = ctx.webServer!.register({
+        kind: 'exact',
+        path: ROUTE_METRICS,
+        handler: (req, res) => {
+          beginRequest(req, res, ROUTE_METRICS);
+          if (req.method !== 'GET') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          writeJson(res, 200, metricsPayload());
+        },
+      });
       return () => {
         disposeReveal();
         disposeSkill();
+        disposeMetrics();
       };
-    }, 'dsh-better-display: reveal and skill-status routes');
+    }, 'dsh-better-display: reveal, skill-status, and metrics routes');
   }
 }

package/src/flags.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Startup kill switch loaded from flags.json. This is not the reader glass setting. */
+export interface Flags {
+  readonly readerEnabled: boolean;
+}
+
+export const defaultFlags: Flags = { readerEnabled: true };
+
+function locateFlags(start = dirname(fileURLToPath(import.meta.url))): string | undefined {
+  let dir = start;
+  for (let depth = 0; depth < 6; depth += 1) {
+    const candidate = resolve(dir, 'flags.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+function normalize(value: unknown): Flags {
+  const record = value !== null && typeof value === 'object' ? value as { readerEnabled?: unknown } : {};
+  return {
+    readerEnabled: typeof record.readerEnabled === 'boolean' ? record.readerEnabled : defaultFlags.readerEnabled,
+  };
+}
+
+export function loadFlags(source?: string | Flags): Flags {
+  if (source !== undefined && typeof source !== 'string') return normalize(source);
+  try {
+    const path = typeof source === 'string' ? source : locateFlags();
+    if (path === undefined || !existsSync(path)) return { ...defaultFlags };
+    return normalize(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+  } catch {
+    return { ...defaultFlags };
+  }
+}

package/src/log.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+
+export const REDACTED = '[REDACTED]';
+
+const REQUEST_ID_HEADER = 'x-request-id';
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,200}$/;
+
+const SECRET_KEYS = new Set([
+  'authorization',
+  'proxyauthorization',
+  'cookie',
+  'setcookie',
+  'token',
+  'accesstoken',
+  'refreshtoken',
+  'idtoken',
+  'apikey',
+  'apisecret',
+  'secret',
+  'clientsecret',
+  'password',
+  'passwd',
+  'credential',
+  'credentials',
+  'signature',
+  'sig',
+  'jwt',
+  'bearer',
+  'privatekey',
+  'xapikey',
+  'xauthtoken',
+  'xaccesstoken',
+  'auth',
+]);
+
+export type LogFields = Record<string, unknown>;
+
+export interface Logger {
+  info(msg: string, fields?: LogFields): void;
+  warn(msg: string, fields?: LogFields): void;
+  error(msg: string, fields?: LogFields): void;
+}
+
+export interface LoggerOptions {
+  readonly write?: (line: string) => void;
+  readonly base?: LogFields;
+  readonly clock?: () => Date;
+}
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function isSecretKey(key: string): boolean {
+  const normalized = normalizeKey(key);
+  if (SECRET_KEYS.has(normalized)) return true;
+  if (normalized === 'requestid' || normalized === 'xrequestid') return false;
+  return /(?:^|[^a-z])(?:token|secret|password|api[-_]?key)$/i.test(key);
+}
+
+function redactString(value: string): string {
+  const query = value.replace(/([?&#])([^&#=]+)=([^&#]*)/g, (match, sep: string, rawKey: string) => {
+    let key: string;
+    try {
+      key = decodeURIComponent(rawKey.replace(/\+/g, ' '));
+    } catch {
+      key = rawKey;
+    }
+    return isSecretKey(key) ? `${sep}${rawKey}=${REDACTED}` : match;
+  });
+  return query
+    .replace(/\b(Bearer|Basic)\s+\S+/gi, `$1 ${REDACTED}`)
+    .replace(
+      /\b((?:access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|client[_-]?secret|password|passwd|authorization|token|secret))(\s*[:=]\s*)([^\s&]+)/gi,
+      `$1$2${REDACTED}`,
+    );
+}
+
+export function redact(value: unknown): unknown {
+  return redactValue(undefined, value, 0, new WeakSet());
+}
+
+function redactValue(key: string | undefined, value: unknown, depth: number, seen: WeakSet<object>): unknown {
+  if (key !== undefined && isSecretKey(key)) return REDACTED;
+  if (depth > 8) return REDACTED;
+  if (typeof value === 'string') return redactString(value);
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null || value === undefined) return value;
+  if (typeof value !== 'object') return REDACTED;
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Error) {
+    return redactValue(undefined, { name: value.name, message: value.message }, depth + 1, seen);
+  }
+  if (seen.has(value)) return REDACTED;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map(item => redactValue(undefined, item, depth + 1, seen));
+  }
+  const output: Record<string, unknown> = {};
+  for (const [childKey, childValue] of Object.entries(value)) {
+    output[childKey] = redactValue(childKey, childValue, depth + 1, seen);
+  }
+  return output;
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const write = options.write ?? ((line: string) => {
+    console.log(line);
+  });
+  const clock = options.clock ?? (() => new Date());
+  const emit = (level: 'info' | 'warn' | 'error', msg: string, fields?: LogFields): void => {
+    const details = redact({ ...options.base, ...fields });
+    const record = {
+      ...(details !== null && typeof details === 'object' ? details as LogFields : {}),
+      time: clock().toISOString(),
+      level,
+      msg: redactString(msg),
+    };
+    try {
+      write(JSON.stringify(record));
+    } catch {
+      write(JSON.stringify({ time: record.time, level, msg: record.msg, error: 'log record was not serializable' }));
+    }
+  };
+  return {
+    info: (msg, fields) => emit('info', msg, fields),
+    warn: (msg, fields) => emit('warn', msg, fields),
+    error: (msg, fields) => emit('error', msg, fields),
+  };
+}
+
+export function requestIdOf(req: IncomingMessage): string {
+  const raw = req.headers[REQUEST_ID_HEADER];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof value === 'string' && REQUEST_ID_PATTERN.test(value)) return value;
+  return randomUUID();
+}

package/src/metrics.ts

@@ -0,0 +1,50 @@
+export const ROUTE_REVEAL = '/better-display/reveal';
+export const ROUTE_SKILL_STATUS = '/better-display/skill-status';
+export const ROUTE_METRICS = '/better-display/metrics';
+
+export const ROUTE_HITS = [ROUTE_REVEAL, ROUTE_SKILL_STATUS, ROUTE_METRICS] as const;
+
+export interface RouteTiming {
+  count: number;
+  totalMs: number;
+  maxMs: number;
+}
+
+const hits = new Map<string, number>(ROUTE_HITS.map(route => [route, 0]));
+const timings = new Map<string, RouteTiming>(ROUTE_HITS.map(route => [route, { count: 0, totalMs: 0, maxMs: 0 }]));
+
+function snapshotHits(): Record<string, number> {
+  return Object.fromEntries(hits);
+}
+
+function snapshotTimings(): Record<string, RouteTiming> {
+  return Object.fromEntries([...timings].map(([route, timing]) => [route, { ...timing }]));
+}
+
+export function recordRouteHit(route: string): number {
+  const next = (hits.get(route) ?? 0) + 1;
+  hits.set(route, next);
+  return next;
+}
+
+export function recordRouteDuration(route: string, elapsedMs: number): RouteTiming {
+  const ms = Number.isFinite(elapsedMs) && elapsedMs > 0 ? Math.round(elapsedMs) : 0;
+  const current = timings.get(route) ?? { count: 0, totalMs: 0, maxMs: 0 };
+  const next = {
+    count: current.count + 1,
+    totalMs: current.totalMs + ms,
+    maxMs: Math.max(current.maxMs, ms),
+  };
+  timings.set(route, next);
+  return next;
+}
+
+export function metricsPayload(): {
+  counters: { dsh_better_display_route_hits_total: Record<string, number> };
+  timingsMs: Record<string, RouteTiming>;
+} {
+  return {
+    counters: { dsh_better_display_route_hits_total: snapshotHits() },
+    timingsMs: snapshotTimings(),
+  };
+}