crewswarm 0.8.1-beta

package/lib/runtime/task-lease.mjs

@@ -0,0 +1,234 @@
+/**
+ * Task lease + deduplication system — extracted from gateway-bridge.mjs
+ * File-based leases prevent duplicate task execution across multiple agent instances.
+ *
+ * Inject: initTaskLease({ telemetry, sleep, parseJsonSafe })
+ */
+
+import fs     from "fs";
+import path   from "path";
+import os     from "os";
+import crypto from "crypto";
+
+const SHARED_MEMORY_BASE      = process.env.SHARED_MEMORY_DIR      || path.join(os.homedir(), ".crewswarm", "workspace", "shared-memory");
+const SHARED_MEMORY_NAMESPACE = process.env.SHARED_MEMORY_NAMESPACE || "claw-swarm";
+const SWARM_RUNTIME_DIR       = path.join(SHARED_MEMORY_BASE, SHARED_MEMORY_NAMESPACE, "opencrew-rt", "runtime");
+const SWARM_TASK_LEASE_DIR    = path.join(SWARM_RUNTIME_DIR, "task-leases");
+const SWARM_TASK_STATE_DIR    = path.join(SWARM_RUNTIME_DIR, "task-state");
+const SWARM_DLQ_DIR           = path.join(SHARED_MEMORY_BASE, SHARED_MEMORY_NAMESPACE, "opencrew-rt", "dlq");
+
+const CREWSWARM_RT_DISPATCH_LEASE_MS      = Number(process.env.CREWSWARM_RT_DISPATCH_LEASE_MS      || "45000");
+const CREWSWARM_RT_DISPATCH_HEARTBEAT_MS  = Number(process.env.CREWSWARM_RT_DISPATCH_HEARTBEAT_MS  || "10000");
+const CREWSWARM_RT_TASK_STATE_TTL_MS      = Number(process.env.CREWSWARM_RT_TASK_STATE_TTL_MS      || "21600000");
+const CREWSWARM_RT_AGENT                  = process.env.CREWSWARM_RT_AGENT                         || process.env.OPENCREW_RT_AGENT || "crew-coder";
+
+let _telemetry     = () => {};
+let _sleep         = (ms) => new Promise(r => setTimeout(r, ms));
+let _parseJsonSafe = (s, def) => { try { return JSON.parse(s); } catch { return def; } };
+
+export function initTaskLease({ telemetry, sleep, parseJsonSafe } = {}) {
+  if (telemetry)     _telemetry     = telemetry;
+  if (sleep)         _sleep         = sleep;
+  if (parseJsonSafe) _parseJsonSafe = parseJsonSafe;
+}
+
+export function ensureSwarmRuntimeDirs() {
+  fs.mkdirSync(SWARM_RUNTIME_DIR, { recursive: true });
+  fs.mkdirSync(SWARM_TASK_LEASE_DIR, { recursive: true });
+  fs.mkdirSync(SWARM_TASK_STATE_DIR, { recursive: true });
+  fs.mkdirSync(SWARM_DLQ_DIR, { recursive: true });
+}
+
+export function parseTaskState(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return _parseJsonSafe(raw, null);
+  } catch {
+    return null;
+  }
+}
+
+export function taskIdentity({ envelope, payload, incomingType, prompt }) {
+  const explicit = String(payload?.idempotencyKey || payload?.idempotency_key || payload?.dedupeKey || "").trim();
+  if (explicit) return explicit;
+  const taskId = String(envelope?.taskId || "").trim();
+  if (taskId) return `${incomingType}:${taskId}`;
+  const envelopeId = String(envelope?.id || "").trim();
+  if (envelopeId) return `${incomingType}:${envelopeId}`;
+  const base = JSON.stringify({
+    incomingType,
+    from: envelope?.from || "unknown",
+    prompt: String(prompt || "").slice(0, 2000),
+  });
+  return `hash:${crypto.createHash("sha256").update(base).digest("hex")}`;
+}
+
+export function taskKeyFor(identity) {
+  return crypto.createHash("sha256").update(String(identity)).digest("hex");
+}
+
+export function leasePath(taskKey) {
+  return path.join(SWARM_TASK_LEASE_DIR, `${taskKey}.json`);
+}
+
+export function taskStatePath(taskKey) {
+  return path.join(SWARM_TASK_STATE_DIR, `${taskKey}.json`);
+}
+
+export function lockPath(taskKey) {
+  return path.join(SWARM_TASK_LEASE_DIR, `${taskKey}.lock`);
+}
+
+export async function withTaskLock(taskKey, fn) {
+  ensureSwarmRuntimeDirs();
+  const file = lockPath(taskKey);
+  const deadline = Date.now() + Math.max(200, CREWSWARM_RT_DISPATCH_HEARTBEAT_MS);
+  let lastErr;
+  while (Date.now() < deadline) {
+    try {
+      const fd = fs.openSync(file, "wx");
+      try {
+        return await fn();
+      } finally {
+        try { fs.closeSync(fd); } catch {}
+        try { fs.unlinkSync(file); } catch {}
+      }
+    } catch (err) {
+      lastErr = err;
+      if (err?.code !== "EEXIST") throw err;
+      // Add jitter to prevent thundering herd
+      await _sleep(40 + Math.random() * 20);
+    }
+  }
+  throw new Error(`task lock timeout for ${taskKey}: ${lastErr?.message || "unknown"}`);
+}
+
+export function clearStaleTaskState() {
+  try {
+    ensureSwarmRuntimeDirs();
+    const now = Date.now();
+    for (const fileName of fs.readdirSync(SWARM_TASK_STATE_DIR)) {
+      if (!fileName.endsWith(".json")) continue;
+      const fullPath = path.join(SWARM_TASK_STATE_DIR, fileName);
+      const row = parseTaskState(fullPath);
+      if (!row) continue;
+      const ts = Date.parse(String(row.completedAt || row.updatedAt || ""));
+      if (!Number.isFinite(ts)) continue;
+      if (now - ts > CREWSWARM_RT_TASK_STATE_TTL_MS) {
+        try { fs.unlinkSync(fullPath); } catch {}
+      }
+    }
+  } catch {}
+}
+
+export async function claimTaskLease({ taskKey, identity, incomingType, envelope, payload }) {
+  const nowIso = new Date().toISOString();
+  const nowMs = Date.now();
+  return withTaskLock(taskKey, async () => {
+    clearStaleTaskState();
+    const stateFile = taskStatePath(taskKey);
+    const existingState = parseTaskState(stateFile);
+    if (existingState?.status === "done") {
+      return {
+        status: "already_done",
+        owner: existingState.owner || "unknown",
+      };
+    }
+
+    const leaseFile = leasePath(taskKey);
+    const existingLease = parseTaskState(leaseFile) || {};
+    const leaseExpiresAtMs = Date.parse(String(existingLease.leaseExpiresAt || ""));
+    const leaseActive = Number.isFinite(leaseExpiresAtMs) && leaseExpiresAtMs > nowMs;
+    if (leaseActive && existingLease.owner && existingLease.owner !== CREWSWARM_RT_AGENT) {
+      return {
+        status: "claimed_by_other",
+        owner: existingLease.owner,
+        leaseExpiresAt: existingLease.leaseExpiresAt,
+      };
+    }
+
+    const previousAttempts = Number(existingLease.attempt || payload?.retryCount || 0);
+    const attempt = leaseActive && existingLease.owner === CREWSWARM_RT_AGENT
+      ? Math.max(1, previousAttempts)
+      : previousAttempts + 1;
+
+    const leaseRecord = {
+      taskKey,
+      identity,
+      incomingType,
+      owner: CREWSWARM_RT_AGENT,
+      source: envelope?.from || "unknown",
+      attempt,
+      taskId: envelope?.taskId || "",
+      messageId: envelope?.id || "",
+      claimedAt: nowIso,
+      heartbeatAt: nowIso,
+      leaseExpiresAt: new Date(nowMs + CREWSWARM_RT_DISPATCH_LEASE_MS).toISOString(),
+    };
+    fs.writeFileSync(leaseFile, `${JSON.stringify(leaseRecord, null, 2)}\n`, "utf8");
+    _telemetry("realtime_task_claimed", {
+      taskKey,
+      identity,
+      attempt,
+      incomingType,
+      owner: CREWSWARM_RT_AGENT,
+    });
+    return {
+      status: "claimed",
+      attempt,
+      lease: leaseRecord,
+    };
+  });
+}
+
+export function startTaskLeaseHeartbeat(taskKey) {
+  return setInterval(async () => {
+    try {
+      await withTaskLock(taskKey, async () => {
+        const leaseFile = leasePath(taskKey);
+        const existingLease = parseTaskState(leaseFile);
+        if (!existingLease || existingLease.owner !== CREWSWARM_RT_AGENT) return;
+        const nowMs = Date.now();
+        existingLease.heartbeatAt = new Date(nowMs).toISOString();
+        existingLease.leaseExpiresAt = new Date(nowMs + CREWSWARM_RT_DISPATCH_LEASE_MS).toISOString();
+        fs.writeFileSync(leaseFile, `${JSON.stringify(existingLease, null, 2)}\n`, "utf8");
+      });
+    } catch (err) {
+      _telemetry("realtime_task_heartbeat_error", { taskKey, message: err?.message ?? String(err) });
+    }
+  }, Math.max(1000, CREWSWARM_RT_DISPATCH_HEARTBEAT_MS));
+}
+
+export async function finalizeTaskState({ taskKey, identity, status, attempt, error = "", note = "" }) {
+  const completedAt = new Date().toISOString();
+  await withTaskLock(taskKey, async () => {
+    const stateFile = taskStatePath(taskKey);
+    const leaseFile = leasePath(taskKey);
+    const state = {
+      taskKey,
+      identity,
+      status,
+      owner: CREWSWARM_RT_AGENT,
+      attempt,
+      error,
+      note,
+      completedAt,
+      updatedAt: completedAt,
+    };
+    fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    try { fs.unlinkSync(leaseFile); } catch {}
+  });
+}
+
+export async function releaseRuntimeTaskLease(taskKey) {
+  await withTaskLock(taskKey, async () => {
+    const leaseFile = leasePath(taskKey);
+    const lease = parseTaskState(leaseFile);
+    if (!lease || lease.owner !== CREWSWARM_RT_AGENT) return;
+    lease.leaseExpiresAt = new Date(Date.now() - 1).toISOString();
+    lease.releasedAt = new Date().toISOString();
+    fs.writeFileSync(leaseFile, `${JSON.stringify(lease, null, 2)}\n`, "utf8");
+  });
+}
+
+export { SWARM_RUNTIME_DIR, SWARM_TASK_LEASE_DIR, SWARM_TASK_STATE_DIR, SWARM_DLQ_DIR };

package/lib/runtime/telemetry-schema.mjs

@@ -0,0 +1,208 @@
+/**
+ * lib/runtime/telemetry-schema.mjs
+ *
+ * Canonical JSON Schema definitions for crewswarm telemetry events.
+ * Matches docs/OPS-TELEMETRY-SCHEMA.md.
+ *
+ * Exported:
+ *   TELEMETRY_SCHEMAS       — { [eventType]: schema }
+ *   ENVELOPE_REQUIRED       — required envelope fields (all event types)
+ *   validateTelemetryEvent  — validate a parsed event object, returns { ok, errors }
+ *   validateTelemetryLog    — validate all lines in a JSONL file, returns summary
+ */
+
+import fs from "node:fs";
+
+// ── Envelope fields shared by all event types ────────────────────────────────
+
+const ENVELOPE_REQUIRED = ["schemaVersion", "eventType", "eventId", "occurredAt", "source", "correlationId", "data"];
+
+const ENVELOPE_SCHEMA = {
+  type: "object",
+  required: ENVELOPE_REQUIRED,
+  properties: {
+    schemaVersion: { type: "string", pattern: "^\\d+\\.\\d+$" },
+    eventType:     { type: "string", minLength: 1 },
+    eventId:       { type: "string", minLength: 1 },
+    occurredAt:    { type: "string", format: "date-time-ish" },
+    receivedAt:    { type: "string" },
+    source: {
+      type: "object",
+      required: ["component"],
+      properties: {
+        component: { type: "string", minLength: 1 },
+        agentId:   { type: "string" },
+        hostname:  { type: "string" },
+        pid:       { type: "number" },
+      },
+    },
+    correlationId: { type: "string", minLength: 1 },
+    sessionId:     { type: "string" },
+    initiator:     { type: "object" },
+    tags:          { type: "object" },
+    data:          { type: "object" },
+  },
+};
+
+// ── Event-type data schemas ───────────────────────────────────────────────────
+
+const AGENT_PRESENCE_DATA_SCHEMA = {
+  type: "object",
+  required: ["status", "latencyMs", "uptimeSeconds", "heartbeatSeq", "version"],
+  properties: {
+    status:         { type: "string", enum: ["online", "offline", "degraded", "draining"] },
+    latencyMs:      { type: "number", minimum: 0 },
+    uptimeSeconds:  { type: "number", minimum: 0 },
+    queueDepth:     { type: "number", minimum: 0 },
+    lastTaskId:     { type: "string" },
+    heartbeatSeq:   { type: "number", minimum: 0 },
+    capabilities:   { type: "array", items: { type: "string" } },
+    version:        { type: "string", minLength: 1 },
+  },
+};
+
+const TASK_LIFECYCLE_DATA_SCHEMA = {
+  type: "object",
+  required: ["taskId", "agentId", "taskType", "phase", "phaseOrdinal"],
+  properties: {
+    taskId:       { type: "string", minLength: 1 },
+    agentId:      { type: "string", minLength: 1 },
+    taskType:     { type: "string", minLength: 1 },
+    phase:        {
+      type: "string",
+      enum: ["dispatched","accepted","started","needs_approval","approved","rejected","awaiting_input","completed","failed","escalated","cancelled"],
+    },
+    phaseOrdinal: { type: "number", minimum: 0 },
+    durationMs:   { type: "number", minimum: 0 },
+    result:       { type: "object" },
+    error:        { type: "object" },
+    retryStrategy:{ type: "object" },
+    dispatcher:   { type: "object" },
+  },
+};
+
+const ERROR_DATA_SCHEMA = {
+  type: "object",
+  required: ["component", "severity", "errorCode", "message"],
+  properties: {
+    component: { type: "string", minLength: 1 },
+    severity:  { type: "string", enum: ["info", "warn", "error", "critical"] },
+    errorCode: { type: "string", minLength: 1 },
+    message:   { type: "string", minLength: 1 },
+    stack:     { type: "string" },
+    taskId:    { type: "string" },
+    agentId:   { type: "string" },
+    context:   { type: "object" },
+  },
+};
+
+// ── Exported schemas map ──────────────────────────────────────────────────────
+
+export const TELEMETRY_SCHEMAS = {
+  "agent.presence":  { envelope: ENVELOPE_SCHEMA, data: AGENT_PRESENCE_DATA_SCHEMA },
+  "task.lifecycle":  { envelope: ENVELOPE_SCHEMA, data: TASK_LIFECYCLE_DATA_SCHEMA },
+  "error":           { envelope: ENVELOPE_SCHEMA, data: ERROR_DATA_SCHEMA },
+};
+
+// ── Lightweight schema validator (no dependencies) ────────────────────────────
+
+function validateValue(value, schema, path) {
+  const errors = [];
+  if (schema.type) {
+    const actualType = Array.isArray(value) ? "array" : typeof value;
+    if (actualType !== schema.type) {
+      errors.push(`${path}: expected ${schema.type}, got ${actualType}`);
+      return errors;
+    }
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path}: "${value}" not in allowed values [${schema.enum.join(", ")}]`);
+  }
+  if (schema.minLength !== undefined && typeof value === "string" && value.length < schema.minLength) {
+    errors.push(`${path}: string length ${value.length} < minimum ${schema.minLength}`);
+  }
+  if (schema.minimum !== undefined && typeof value === "number" && value < schema.minimum) {
+    errors.push(`${path}: ${value} < minimum ${schema.minimum}`);
+  }
+  if (schema.pattern && typeof value === "string" && !new RegExp(schema.pattern).test(value)) {
+    errors.push(`${path}: "${value}" does not match pattern ${schema.pattern}`);
+  }
+  if (schema.type === "object" && schema.required) {
+    for (const key of schema.required) {
+      if (value[key] === undefined || value[key] === null) {
+        errors.push(`${path}.${key}: required field missing`);
+      }
+    }
+  }
+  if (schema.type === "object" && schema.properties && typeof value === "object") {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (value[key] !== undefined && value[key] !== null) {
+        errors.push(...validateValue(value[key], propSchema, `${path}.${key}`));
+      }
+    }
+  }
+  if (schema.type === "array" && schema.items && Array.isArray(value)) {
+    value.forEach((item, i) => {
+      errors.push(...validateValue(item, schema.items, `${path}[${i}]`));
+    });
+  }
+  return errors;
+}
+
+/**
+ * Validate a single parsed telemetry event object.
+ * @param {object} event  — parsed JSON event
+ * @returns {{ ok: boolean, errors: string[], eventType: string }}
+ */
+export function validateTelemetryEvent(event) {
+  if (!event || typeof event !== "object") {
+    return { ok: false, errors: ["event is not an object"], eventType: "unknown" };
+  }
+  const eventType = event.eventType || "unknown";
+  const errors = [];
+
+  // Envelope validation (common to all types)
+  errors.push(...validateValue(event, ENVELOPE_SCHEMA, "event"));
+
+  // Data validation (type-specific)
+  const typeSchema = TELEMETRY_SCHEMAS[eventType];
+  if (typeSchema && event.data && typeof event.data === "object") {
+    errors.push(...validateValue(event.data, typeSchema.data, "event.data"));
+  } else if (!typeSchema) {
+    // Unknown event type — only warn, don't fail (forward-compat)
+    errors.push(`event.eventType: unknown type "${eventType}" (not in schema — new type or typo)`);
+  }
+
+  return { ok: errors.length === 0, errors, eventType };
+}
+
+/**
+ * Validate all lines in a JSONL telemetry log file.
+ * @param {string} filePath
+ * @returns {{ total: number, valid: number, invalid: number, unknownType: number, issues: Array }}
+ */
+export function validateTelemetryLog(filePath) {
+  const summary = { total: 0, valid: 0, invalid: 0, unknownType: 0, issues: [] };
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return summary;
+  }
+  for (const line of raw.split("\n").filter(l => l.trim())) {
+    summary.total++;
+    let parsed;
+    try { parsed = JSON.parse(line); }
+    catch { summary.invalid++; summary.issues.push({ line: summary.total, error: "invalid JSON" }); continue; }
+    const result = validateTelemetryEvent(parsed);
+    if (!result.ok) {
+      const isUnknownType = result.errors.some(e => e.includes("unknown type"));
+      if (isUnknownType) summary.unknownType++;
+      else summary.invalid++;
+      summary.issues.push({ line: summary.total, eventType: result.eventType, errors: result.errors });
+    } else {
+      summary.valid++;
+    }
+  }
+  return summary;
+}

package/lib/runtime/telemetry.mjs

@@ -0,0 +1,101 @@
+/**
+ * Telemetry and ops snapshot — extracted from crew-lead.mjs
+ */
+
+let _broadcastSSE = () => {};
+
+export function initTelemetry({ broadcastSSE }) {
+  if (broadcastSSE) _broadcastSSE = broadcastSSE;
+}
+
+export const TELEMETRY_SCHEMA_VERSION = "1.1";
+export const TELEMETRY_EVENT_LIMIT = 100;
+export const telemetryEvents = [];
+export const taskPhaseOrdinal = new Map();
+
+export const OPS_EVENT_LIMIT = 200;
+export const OPS_EVENTS = [];
+export const OPS_COUNTERS = {
+  tasksDispatched: 0,
+  tasksCompleted: 0,
+  pipelinesStarted: 0,
+  pipelinesCompleted: 0,
+  webhooksReceived: 0,
+  skillsApproved: 0,
+  skillsRejected: 0,
+};
+
+export function nextPhaseOrdinal(taskId) {
+  const n = (taskPhaseOrdinal.get(taskId) || 0) + 1;
+  taskPhaseOrdinal.set(taskId, n);
+  return n;
+}
+
+export function emitTaskLifecycle(phase, data) {
+  const { taskId, agentId } = data;
+  const eventId = "evt_" + Date.now() + "_" + Math.random().toString(36).slice(2, 10);
+  const envelope = {
+    schemaVersion: TELEMETRY_SCHEMA_VERSION,
+    eventType: "task.lifecycle",
+    eventId,
+    occurredAt: new Date().toISOString(),
+    source: { component: "crew-lead" },
+    correlationId: taskId ? "task:" + taskId : "task:unknown",
+    data: {
+      taskId: taskId || "",
+      agentId: agentId || "",
+      taskType: data.taskType || "task",
+      phase,
+      phaseOrdinal: nextPhaseOrdinal(taskId || "global"),
+      ...(data.durationMs != null && { durationMs: data.durationMs }),
+      ...(data.result && { result: data.result }),
+      ...(data.error && { error: data.error }),
+    },
+  };
+  telemetryEvents.push(envelope);
+  if (telemetryEvents.length > TELEMETRY_EVENT_LIMIT) telemetryEvents.shift();
+  _broadcastSSE({ type: "telemetry", payload: envelope });
+}
+
+export function readTelemetryEvents(limit = 25) {
+  const n = Math.min(Number(limit) || 25, TELEMETRY_EVENT_LIMIT);
+  return telemetryEvents.slice(-n);
+}
+
+export function bumpOpsCounter(key, delta = 1) {
+  OPS_COUNTERS[key] = (OPS_COUNTERS[key] || 0) + delta;
+}
+
+export function recordOpsEvent(type, fields = {}) {
+  const entry = { ts: Date.now(), type, ...fields };
+  OPS_EVENTS.push(entry);
+  if (OPS_EVENTS.length > OPS_EVENT_LIMIT) OPS_EVENTS.shift();
+  return entry;
+}
+
+export function readOpsEvents(limit = 25) {
+  if (!Number.isFinite(limit) || limit <= 0) limit = 25;
+  const sliceCount = Math.min(Math.trunc(limit), OPS_EVENT_LIMIT);
+  return OPS_EVENTS.slice(sliceCount * -1);
+}
+
+export function buildTaskText(taskSpec) {
+  if (typeof taskSpec === "string") return taskSpec;
+  let text = taskSpec.task || "";
+  if (taskSpec.verify || taskSpec.done) {
+    text += "\n\n## Acceptance criteria";
+    if (taskSpec.verify) text += `\n- Verify: ${taskSpec.verify}`;
+    if (taskSpec.done)   text += `\n- Done when: ${taskSpec.done}`;
+  }
+  return text;
+}
+
+export function resolveAgentId(cfg, nameOrId) {
+  if (!nameOrId) return null;
+  const id = String(nameOrId).trim();
+  if (cfg.knownAgents && cfg.knownAgents.includes(id)) return id;
+  const roster = cfg.agentRoster || [];
+  const byName = roster.find(a => (a.name || "").toLowerCase() === id.toLowerCase());
+  if (byName) return byName.id;
+  return id;
+}

package/lib/runtime/utils.mjs

@@ -0,0 +1,64 @@
+/**
+ * Formatting utilities and telemetry reader — extracted from gateway-bridge.mjs
+ * Pure functions with no external injection needed.
+ */
+
+import fs   from "fs";
+import os   from "os";
+import path from "path";
+
+const LEGACY_STATE_DIR = path.join(os.homedir(), ".openclaw");
+const TELEMETRY_DIR    = path.join(LEGACY_STATE_DIR, "telemetry");
+export const TELEMETRY_LOG = path.join(TELEMETRY_DIR, "events.log");
+
+export function formatError(err) {
+  const msg = err?.message ?? String(err);
+  const lower = msg.toLowerCase();
+  let hint = "Hint: run --quickstart to verify connection and channel status.";
+  if (lower.includes("enoent") || lower.includes("device.json") || lower.includes("openclaw.json")) {
+    hint = `Hint: initialize config (e.g. run install) so identity/config exist under ~/.crewswarm or legacy path.`;
+  } else if (lower.includes("econnrefused") || lower.includes("connect") || lower.includes("websocket")) {
+    hint = "Hint: start the local gateway service, then re-run with --quickstart.";
+  } else if (lower.includes("timeout")) {
+    hint = "Hint: gateway may be busy; retry in a few seconds or use --status to verify responsiveness.";
+  }
+  return `❌ ${msg}\n${hint}`;
+}
+
+export function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+export function median(numbers) {
+  if (!numbers.length) return null;
+  const sorted = [...numbers].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+
+export function percentile(numbers, p) {
+  if (!numbers.length) return null;
+  const sorted = [...numbers].sort((a, b) => a - b);
+  const idx = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(sorted.length - 1, idx))];
+}
+
+export function readTelemetryEvents(limit = 20000) {
+  try {
+    if (!fs.existsSync(TELEMETRY_LOG)) return [];
+    const lines = fs.readFileSync(TELEMETRY_LOG, "utf8").split("\n").filter(Boolean);
+    const tail = lines.slice(-limit);
+    const events = [];
+    for (const line of tail) {
+      try {
+        const row = JSON.parse(line);
+        if (row?.event && row?.timestamp) events.push(row);
+      } catch {}
+    }
+    return events;
+  } catch {
+    return [];
+  }
+}
+