@lensmcp/protocol-types 1.22.5 → 1.23.0

package/index.d.ts

@@ -12,3 +12,4 @@ export * from './lib/capture-demand.js';
 export * from './lib/bounded-clone.js';
 export * from './lib/bounded-map.js';
 export * from './lib/flood-guard.js';
+export * from './lib/dashboard.js';

package/index.js

@@ -1 +1 @@
-"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";
+"use strict";export*from"./lib/schema-version.js";export*from"./lib/source-location.js";export*from"./lib/context.js";export*from"./lib/event.js";export*from"./lib/node.js";export*from"./lib/edge.js";export*from"./lib/attributes.js";export*from"./lib/producer-health.js";export*from"./lib/resources.js";export*from"./lib/tokens.js";export*from"./lib/capture-demand.js";export*from"./lib/bounded-clone.js";export*from"./lib/bounded-map.js";export*from"./lib/flood-guard.js";export*from"./lib/dashboard.js";

package/lib/bounded-clone.js

@@ -1 +1 @@
-"use strict";var T=Object.defineProperty;var i=(e,t)=>T(e,"name",{value:t,configurable:!0});var h=Object.defineProperty,l=i((e,t)=>h(e,"name",{value:t,configurable:!0}),"_");export const DEFAULT_RAW_BYTE_LIMIT=32768,DEFAULT_MAX_STRING_BYTES=4096,DEFAULT_MAX_ARRAY_ITEMS=64,DEFAULT_MAX_DEPTH=12,CHEAP_ENTRY_BYTES=512,NOMINAL_DEEP_BYTES=32,DEEP_REPORT_DEPTH=64,SKELETON_STRING_BYTES=256,MAX_RECORDED_PATHS=20,TRUNCATION_MARKER_KEY="__lensmcpTruncation",TRUNCATED_VALUE_KEY="__lensmcpTruncated";export function estimateJsonBytes(e,t=Number.POSITIVE_INFINITY,r=12){return y(e,t,r,32)}i(estimateJsonBytes,"estimateJsonBytes"),l(estimateJsonBytes,"estimateJsonBytes");export function exceedsJsonByteBudget(e,t,r=12){return y(e,t,r,Number.POSITIVE_INFINITY)>t}i(exceedsJsonByteBudget,"exceedsJsonByteBudget"),l(exceedsJsonByteBudget,"exceedsJsonByteBudget");function y(e,t,r,a){switch(typeof e){case"undefined":case"function":case"symbol":return 0;case"boolean":return 5;case"number":return Number.isFinite(e)?8:4;case"bigint":return 20;case"string":return e.length+2;default:break}if(e===null)return 4;if(r<=0)return a;if(e instanceof Date)return 26;if(Array.isArray(e)){let n=2;for(let s=0;s<e.length;s++)if(n+=y(e[s],t-n,r-1,a)+1,n>t)return n;return n}let u=2;const o=e;for(const n in o){if(!Object.prototype.hasOwnProperty.call(o,n))continue;const s=y(o[n],t-u,r-1,a);if(s!==0&&(u+=n.length+4+s,u>t))return u}return u}i(y,"T"),l(y,"walk");function g(e,t){e.truncatedAnything=!0,e.paths.length<20&&e.paths.push(t||"<root>")}i(g,"A"),l(g,"record");function f(e,t,r){return g(e,r),{[TRUNCATED_VALUE_KEY]:!0,originalBytes:estimateJsonBytes(t,Number.POSITIVE_INFINITY,64)}}i(f,"I"),l(f,"stub");function p(e){if(e===null)return!0;const t=typeof e;return t==="number"||t==="boolean"||t==="string"||t==="bigint"}i(p,"y"),l(p,"isScalar");export function clampValue(e,t,r,a){if(typeof e=="string"){const u=t.budget<=0?256:t.maxStringBytes;if(e.length+2<=u)return t.budget-=e.length+2,e;const o=Math.max(0,u-64);return g(t,a),t.budget-=o,`${e.slice(0,o)}\u2026[lensmcp truncated: ${e.length-o} more chars]`}return e===null||typeof e!="object"?(t.budget-=y(e,Number.POSITIVE_INFINITY,1,32),e):r<=0?f(t,e,a):e instanceof Date?(t.budget-=26,e):Array.isArray(e)?m(e,t,r,a):b(e,t,r,a)}i(clampValue,"clampValue"),l(clampValue,"clampValue");function m(e,t,r,a){const u=[],o=Math.min(e.length,t.maxArrayItems);for(let n=0;n<o&&!(t.budget<=0);n++)u.push(clampValue(e[n],t,r-1,`${a}[${n}]`));return u.length<e.length&&g(t,`${a}[] (+${e.length-u.length} items dropped)`),u}i(m,"f"),l(m,"clampArray");function b(e,t,r,a){const u={};let o;const n=t.budget<=0;for(const s in e){if(!Object.prototype.hasOwnProperty.call(e,s))continue;const c=e[s],I=y(c,512,r-1,Number.POSITIVE_INFINITY);if(I<=512&&(!n||p(c))){u[s]=c,t.budget-=s.length+4+I;continue}(o??=[]).push({key:s,bytes:I})}if(!o)return u;o.sort((s,c)=>s.bytes===c.bytes?0:s.bytes<c.bytes?-1:1);for(const{key:s}of o){const c=a?`${a}.${s}`:s;u[s]=clampValue(e[s],t,r-1,c)}return u}i(b,"m"),l(b,"clampObject");export function boundedClone(e,t={}){const r=t.rawByteLimit??32768,a=t.maxDepth??12;if(r<=0)return{value:void 0,truncated:!1,originalBytes:0,keptBytes:0,paths:[]};if(e==null)return{value:e,truncated:!1,originalBytes:0,keptBytes:0,paths:[]};if(!exceedsJsonByteBudget(e,r,a)){const c=estimateJsonBytes(e,r,a),I={budget:r,maxStringBytes:t.maxStringBytes??4096,maxArrayItems:t.maxArrayItems??64,paths:[],truncatedAnything:!1};return{value:clampValue(e,I,a,""),truncated:!1,originalBytes:c,keptBytes:c,paths:[]}}const u=estimateJsonBytes(e,Number.POSITIVE_INFINITY,64),o={budget:r,maxStringBytes:t.maxStringBytes??4096,maxArrayItems:t.maxArrayItems??64,paths:[],truncatedAnything:!1},n=clampValue(e,o,a,""),s=estimateJsonBytes(n,Number.POSITIVE_INFINITY,a);if(o.truncatedAnything&&n!==null&&typeof n=="object"&&!Array.isArray(n)){const c={truncated:!0,originalBytes:u,keptBytes:s,paths:o.paths};n[TRUNCATION_MARKER_KEY]=c}return{value:n,truncated:o.truncatedAnything,originalBytes:u,keptBytes:s,paths:o.paths}}i(boundedClone,"boundedClone"),l(boundedClone,"boundedClone");
+"use strict";var T=Object.defineProperty;var c=(t,e)=>T(t,"name",{value:e,configurable:!0});var h=Object.defineProperty,l=c((t,e)=>h(t,"name",{value:e,configurable:!0}),"i"),_=Object.defineProperty,y=l((t,e)=>_(t,"name",{value:e,configurable:!0}),"_");export const DEFAULT_RAW_BYTE_LIMIT=32768,DEFAULT_MAX_STRING_BYTES=4096,DEFAULT_MAX_ARRAY_ITEMS=64,DEFAULT_MAX_DEPTH=12,CHEAP_ENTRY_BYTES=512,NOMINAL_DEEP_BYTES=32,DEEP_REPORT_DEPTH=64,SKELETON_STRING_BYTES=256,MAX_RECORDED_PATHS=20,TRUNCATION_MARKER_KEY="__lensmcpTruncation",TRUNCATED_VALUE_KEY="__lensmcpTruncated";export function estimateJsonBytes(t,e=Number.POSITIVE_INFINITY,n=12){return g(t,e,n,32)}c(estimateJsonBytes,"estimateJsonBytes"),l(estimateJsonBytes,"estimateJsonBytes"),y(estimateJsonBytes,"estimateJsonBytes");export function exceedsJsonByteBudget(t,e,n=12){return g(t,e,n,Number.POSITIVE_INFINITY)>e}c(exceedsJsonByteBudget,"exceedsJsonByteBudget"),l(exceedsJsonByteBudget,"exceedsJsonByteBudget"),y(exceedsJsonByteBudget,"exceedsJsonByteBudget");function g(t,e,n,a){switch(typeof t){case"undefined":case"function":case"symbol":return 0;case"boolean":return 5;case"number":return Number.isFinite(t)?8:4;case"bigint":return 20;case"string":return t.length+2;default:break}if(t===null)return 4;if(n<=0)return a;if(t instanceof Date)return 26;if(Array.isArray(t)){let r=2;for(let u=0;u<t.length;u++)if(r+=g(t[u],e-r,n-1,a)+1,r>e)return r;return r}let s=2;const o=t;for(const r in o){if(!Object.prototype.hasOwnProperty.call(o,r))continue;const u=g(o[r],e-s,n-1,a);if(u!==0&&(s+=r.length+4+u,s>e))return s}return s}c(g,"y"),l(g,"T"),y(g,"walk");function f(t,e){t.truncatedAnything=!0,t.paths.length<20&&t.paths.push(e||"<root>")}c(f,"g"),l(f,"A"),y(f,"record");function p(t,e,n){return f(t,n),{[TRUNCATED_VALUE_KEY]:!0,originalBytes:estimateJsonBytes(e,Number.POSITIVE_INFINITY,64)}}c(p,"f"),l(p,"I"),y(p,"stub");function m(t){if(t===null)return!0;const e=typeof t;return e==="number"||e==="boolean"||e==="string"||e==="bigint"}c(m,"p"),l(m,"y"),y(m,"isScalar");export function clampValue(t,e,n,a){if(typeof t=="string"){const s=e.budget<=0?256:e.maxStringBytes;if(t.length+2<=s)return e.budget-=t.length+2,t;const o=Math.max(0,s-64);return f(e,a),e.budget-=o,`${t.slice(0,o)}\u2026[lensmcp truncated: ${t.length-o} more chars]`}return t===null||typeof t!="object"?(e.budget-=g(t,Number.POSITIVE_INFINITY,1,32),t):n<=0?p(e,t,a):t instanceof Date?(e.budget-=26,t):Array.isArray(t)?b(t,e,n,a):d(t,e,n,a)}c(clampValue,"clampValue"),l(clampValue,"clampValue"),y(clampValue,"clampValue");function b(t,e,n,a){const s=[],o=Math.min(t.length,e.maxArrayItems);for(let r=0;r<o&&!(e.budget<=0);r++)s.push(clampValue(t[r],e,n-1,`${a}[${r}]`));return s.length<t.length&&f(e,`${a}[] (+${t.length-s.length} items dropped)`),s}c(b,"m"),l(b,"f"),y(b,"clampArray");function d(t,e,n,a){const s={};let o;const r=e.budget<=0;for(const u in t){if(!Object.prototype.hasOwnProperty.call(t,u))continue;const i=t[u],I=g(i,512,n-1,Number.POSITIVE_INFINITY);if(I<=512&&(!r||m(i))){s[u]=i,e.budget-=u.length+4+I;continue}(o??=[]).push({key:u,bytes:I})}if(!o)return s;o.sort((u,i)=>u.bytes===i.bytes?0:u.bytes<i.bytes?-1:1);for(const{key:u}of o){const i=a?`${a}.${u}`:u;s[u]=clampValue(t[u],e,n-1,i)}return s}c(d,"b"),l(d,"m"),y(d,"clampObject");export function boundedClone(t,e={}){const n=e.rawByteLimit??32768,a=e.maxDepth??12;if(n<=0)return{value:void 0,truncated:!1,originalBytes:0,keptBytes:0,paths:[]};if(t==null)return{value:t,truncated:!1,originalBytes:0,keptBytes:0,paths:[]};if(!exceedsJsonByteBudget(t,n,a)){const i=estimateJsonBytes(t,n,a),I={budget:n,maxStringBytes:e.maxStringBytes??4096,maxArrayItems:e.maxArrayItems??64,paths:[],truncatedAnything:!1};return{value:clampValue(t,I,a,""),truncated:!1,originalBytes:i,keptBytes:i,paths:[]}}const s=estimateJsonBytes(t,Number.POSITIVE_INFINITY,64),o={budget:n,maxStringBytes:e.maxStringBytes??4096,maxArrayItems:e.maxArrayItems??64,paths:[],truncatedAnything:!1},r=clampValue(t,o,a,""),u=estimateJsonBytes(r,Number.POSITIVE_INFINITY,a);if(o.truncatedAnything&&r!==null&&typeof r=="object"&&!Array.isArray(r)){const i={truncated:!0,originalBytes:s,keptBytes:u,paths:o.paths};r[TRUNCATION_MARKER_KEY]=i}return{value:r,truncated:o.truncatedAnything,originalBytes:s,keptBytes:u,paths:o.paths}}c(boundedClone,"boundedClone"),l(boundedClone,"boundedClone"),y(boundedClone,"boundedClone");

package/lib/bounded-map.js

@@ -1 +1 @@
-"use strict";var c=Object.defineProperty;var t=(e,r)=>c(e,"name",{value:r,configurable:!0});var i=Object.defineProperty,s=t((e,r)=>i(e,"name",{value:r,configurable:!0}),"o");export function capMap(e,r){if(e.size<=r)return 0;let n=0;const o=e.keys();for(;e.size>r;){const a=o.next();if(a.done)break;e.delete(a.value)&&(n+=1)}return n}t(capMap,"capMap"),s(capMap,"capMap");export const MAX_PRODUCER_KEYS=256;
+"use strict";var i=Object.defineProperty;var t=(e,a)=>i(e,"name",{value:a,configurable:!0});var p=Object.defineProperty,o=t((e,a)=>p(e,"name",{value:a,configurable:!0}),"t"),s=Object.defineProperty,u=o((e,a)=>s(e,"name",{value:a,configurable:!0}),"o");export function capMap(e,a){if(e.size<=a)return 0;let r=0;const c=e.keys();for(;e.size>a;){const n=c.next();if(n.done)break;e.delete(n.value)&&(r+=1)}return r}t(capMap,"capMap"),o(capMap,"capMap"),u(capMap,"capMap");export const MAX_PRODUCER_KEYS=256;

package/lib/bounded-writer.js

@@ -1 +1 @@
-"use strict";var y=Object.defineProperty;var r=(e,t)=>y(e,"name",{value:t,configurable:!0});var v=Object.defineProperty,o=r((e,t)=>v(e,"name",{value:t,configurable:!0}),"c");import{renameSync as l,statSync as f,unlinkSync as x}from"node:fs";export function eventMaxBytes(e=process.env){const t=Number(e.LENSMCP_EVENT_MAX_BYTES);return Number.isFinite(t)&&t>0?t:50*1024*1024}r(eventMaxBytes,"eventMaxBytes"),o(eventMaxBytes,"eventMaxBytes");export function eventMaxFiles(e=process.env){const t=Number(e.LENSMCP_EVENT_MAX_FILES);return Number.isFinite(t)&&t>=1&&t<=20?Math.floor(t):5}r(eventMaxFiles,"eventMaxFiles"),o(eventMaxFiles,"eventMaxFiles");const E=1024*1024,a=new Map;export function maybeRotateEventFile(e,t,i){const s=(a.get(e)??0)+t,c=i?.maxBytes??eventMaxBytes(),u=i?.maxFiles??eventMaxFiles(),m=Math.min(E,c);if(s<m){a.set(e,s);return}try{const n=f(e).size;if(a.set(e,0),n<=c)return}catch{a.set(e,s);return}try{x(`${e}.${u}`)}catch{}for(let n=u-1;n>=1;n--)try{l(`${e}.${n}`,`${e}.${n+1}`)}catch{}try{l(e,`${e}.1`)}catch{}}r(maybeRotateEventFile,"maybeRotateEventFile"),o(maybeRotateEventFile,"maybeRotateEventFile");export function resetRotationThrottle(e){e===void 0?a.clear():a.delete(e)}r(resetRotationThrottle,"resetRotationThrottle"),o(resetRotationThrottle,"resetRotationThrottle");
+"use strict";var m=Object.defineProperty;var r=(t,e)=>m(t,"name",{value:e,configurable:!0});var f=Object.defineProperty,o=r((t,e)=>f(t,"name",{value:e,configurable:!0}),"r"),x=Object.defineProperty,s=o((t,e)=>x(t,"name",{value:e,configurable:!0}),"c");import{renameSync as v,statSync as M,unlinkSync as E}from"node:fs";export function eventMaxBytes(t=process.env){const e=Number(t.LENSMCP_EVENT_MAX_BYTES);return Number.isFinite(e)&&e>0?e:50*1024*1024}r(eventMaxBytes,"eventMaxBytes"),o(eventMaxBytes,"eventMaxBytes"),s(eventMaxBytes,"eventMaxBytes");export function eventMaxFiles(t=process.env){const e=Number(t.LENSMCP_EVENT_MAX_FILES);return Number.isFinite(e)&&e>=1&&e<=20?Math.floor(e):5}r(eventMaxFiles,"eventMaxFiles"),o(eventMaxFiles,"eventMaxFiles"),s(eventMaxFiles,"eventMaxFiles");const b=1024*1024,a=new Map;export function maybeRotateEventFile(t,e,c){const i=(a.get(t)??0)+e,l=c?.maxBytes??eventMaxBytes(),u=c?.maxFiles??eventMaxFiles(),y=Math.min(b,l);if(i<y){a.set(t,i);return}try{const n=M(t).size;if(a.set(t,0),n<=l)return}catch{a.set(t,i);return}try{E(`${t}.${u}`)}catch{}for(let n=u-1;n>=1;n--)try{v(`${t}.${n}`,`${t}.${n+1}`)}catch{}try{v(t,`${t}.1`)}catch{}}r(maybeRotateEventFile,"maybeRotateEventFile"),o(maybeRotateEventFile,"maybeRotateEventFile"),s(maybeRotateEventFile,"maybeRotateEventFile");export function resetRotationThrottle(t){t===void 0?a.clear():a.delete(t)}r(resetRotationThrottle,"resetRotationThrottle"),o(resetRotationThrottle,"resetRotationThrottle"),s(resetRotationThrottle,"resetRotationThrottle");

package/lib/dashboard.d.ts

@@ -0,0 +1,505 @@
+/**
+ * The wire contract between the per-project dashboard server
+ * (`servers/lensmcp-mcp/src/dashboard/*`) and its browser UI (`libs/dashboard-ui`).
+ *
+ * Plain interfaces only — the UI imports them as types, so nothing here may pull runtime code
+ * into the browser bundle. Every shape is additive-only once shipped: an older UI reading a newer
+ * server must keep working, so fields are added, never renamed or repurposed.
+ *
+ * One SSE connection (`GET /api/stream`) carries every live panel as a typed event
+ * ({@link DashStreamEvent}); the heavier reads (`/api/flow`, `/api/resource`, `/api/logs`) are
+ * on-demand GETs.
+ */
+/** Bumped only on a breaking change to the stream framing itself. */
+export declare const DASHBOARD_PROTOCOL = 1;
+/** The swimlane a flow event belongs to (mirrors `FlowArea` in `@lensmcp/core`'s flow-shape). */
+export type DashFlowArea = 'browser' | 'state' | 'network' | 'gateway' | 'services' | 'data' | 'ai';
+export type DashSeverity = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+export interface DashWorkspace {
+    /** The workspace key — the `/<key>` the gateway mounts this dashboard under. */
+    key: string;
+    /** Human name for the header (the key, or the workspace folder's name). */
+    name: string;
+    /** The mount prefix, e.g. `/test-lensmcp`; empty when served at `/`. */
+    base: string;
+}
+/** First frame on every stream connection. */
+export interface DashHello {
+    protocol: number;
+    sessionId: string;
+    startedAt: number;
+    /** Whether `/api/flow?raw=1` is allowed (loopback bind only). */
+    rawAllowed: boolean;
+    workspace: DashWorkspace;
+    /** The log ring's current sequence — resume `/api/logs?since=` from here. */
+    logSeq: number;
+}
+/**
+ * Whether the dev gateway in front of this workspace is serving.
+ *
+ * `role` matters for the reading: a workspace that is a GUEST on another workspace's `:443`
+ * daemon never sees that daemon's `gateway-up` event (it lands on the owner's bus), so liveness
+ * there is established from the process tree, not from the event stream.
+ */
+export interface DashGatewayLiveness {
+    state: 'live' | 'down' | 'unknown';
+    role: 'gateway-child' | 'standalone';
+    ports: number[];
+    /** When it was last seen up (epoch ms), if known. */
+    since?: number;
+    /** One line on HOW this was decided — shown in the tooltip, so the verdict is auditable. */
+    evidence: string;
+}
+export interface DashSetupIssue {
+    id: string;
+    title: string;
+    detail: string;
+    /** A shell command that fixes it, when there is one. */
+    fix?: string;
+}
+export type DashSessionPhase = 'empty' | 'live' | 'setup-incomplete';
+export interface DashSession {
+    phase: DashSessionPhase;
+    gateway: DashGatewayLiveness;
+    /** `agent://current-status`'s verdict — the same one the coding agent reads. */
+    status: 'starting' | 'clean' | 'warning' | 'failing';
+    /** One sentence answering "is anything wrong right now?". */
+    headline: string;
+    flowCount: number;
+    eventCount: number;
+    setupIssues: DashSetupIssue[];
+}
+export type DashServiceState = 'up' | 'starting' | 'idle' | 'down' | 'wedged' | 'crash-looping' | 'unknown';
+/** Aggregates over a sliding window (see `DashKpis.windowSec`). `null` = no samples. */
+export interface DashWindowStats {
+    count: number;
+    errors: number;
+    /** errors / count over the window, 0..1 — `null` when there were no requests. */
+    errorRate: number | null;
+    p50: number | null;
+    p95: number | null;
+    avgMs: number | null;
+    /** Latency samples behind p50/p95 — may be fewer than `count` (see `sampled`). */
+    samples: number;
+    /**
+     * The percentiles come from the requests that carried lens headers (a subset of `count`),
+     * not from every proxied request.
+     */
+    sampled: boolean;
+}
+export interface DashService {
+    project: string;
+    /** eager = always warm · lazy = scales from zero · web = a frontend dev server (no pods). */
+    kind: 'eager' | 'lazy' | 'web';
+    state: DashServiceState;
+    /** Plain-language reason for a non-`up` state ("idle — scaled to zero after 10m"). */
+    stateReason?: string;
+    host?: string;
+    path?: string;
+    internalHost?: string;
+    port?: number;
+    internalPort?: number;
+    pods: {
+        running: number;
+        names: string[];
+        min?: number;
+        max?: number;
+    };
+    workers: string[];
+    lastColdStartMs?: number;
+    restarts: number;
+    buildFailed: boolean;
+    /** Last build/runtime error lines the gateway saw from this service's pod output. */
+    errorLines: string[];
+    auth?: {
+        default?: string;
+        overrides: number;
+    };
+    /** Public traffic into this service since the dashboard started. */
+    traffic: {
+        count: number;
+        errors: number;
+        avgMs: number | null;
+        lastSeenAt?: number;
+    };
+    /** Windowed stats + a request sparkline (per `DashKpis.sparkBucketSec`). */
+    window?: DashWindowStats & {
+        req60: number;
+        spark: number[];
+    };
+    /** Truncated sha256 of the east-west key — never the key. */
+    keyFingerprint?: string;
+    lastEvent?: {
+        at: number;
+        title: string;
+    };
+}
+export interface DashRoute {
+    host: string;
+    project: string;
+    count: number;
+    errors: number;
+    avgMs: number | null;
+    lastSeenAt?: number;
+}
+/** Service → service (east-west) traffic. */
+export interface DashEdge {
+    caller: string;
+    callee: string;
+    host: string;
+    count: number;
+    errors: number;
+    avgMs: number | null;
+    lastSeenAt: number;
+}
+export type DashBackendKind = 'db' | 'redis' | 'queue' | 'external' | 'fs' | 'exec';
+export interface DashBackend {
+    id: string;
+    kind: DashBackendKind;
+    name: string;
+    usedBy: string[];
+    ops: number;
+    lastSeenAt: number;
+    /** BullMQ-style counts + recent jobs, for `kind: 'queue'`. */
+    queue?: {
+        counts: Record<string, number>;
+        recent: Array<{
+            id: string;
+            name?: string;
+            state?: string;
+            at?: number;
+        }>;
+    };
+}
+export interface DashHostCheck {
+    host: string;
+    v4: boolean;
+    v6: boolean;
+}
+export interface DashCluster {
+    at: number;
+    gateway: DashGatewayLiveness;
+    services: DashService[];
+    routes: DashRoute[];
+    edges: DashEdge[];
+    backends: DashBackend[];
+    hosts: DashHostCheck[];
+    /** Appends the missing /etc/hosts lines — present only when a host does not resolve. */
+    hostsFix?: string;
+    trustCommand: string;
+    recent: Array<{
+        at: number;
+        title: string;
+        severity: string;
+    }>;
+}
+export interface DashKpis {
+    at: number;
+    /** The window `last` covers, in seconds. */
+    windowSec: number;
+    /** Requests through the gateway in the last 60 s. */
+    req60: number;
+    last: DashWindowStats;
+    sparkBucketSec: number;
+    /** Oldest → newest. `p95` holds `null` for buckets without latency samples. */
+    spark: {
+        req: number[];
+        errors: number[];
+        p95: Array<number | null>;
+    };
+}
+export type DashWorst = 'ok' | 'warn' | 'error';
+export interface DashFlowSummary {
+    flowId: string;
+    originType?: string;
+    originNodeId?: string;
+    startedAt: number;
+    lastSeenAt: number;
+    eventCount: number;
+    /** Human headline: `click · app.tsx:41 → GET /api/storefront`. */
+    headline: string;
+    /** What started it, in words: `click`, `page load /lab`, `submit`… */
+    originLabel: string;
+    /** Where in the source it started (`app.tsx:41`), when known. */
+    originWhere?: string;
+    /** The first request the flow made, if any. */
+    request?: {
+        method: string;
+        path: string;
+        status?: number;
+    };
+    worst: DashWorst;
+    /** Wall time of the ACTIVE part (idle tails like pool bookkeeping excluded). */
+    durationMs: number;
+    /** Event counts per swimlane — drives the lane-mix bar. */
+    lanes: Partial<Record<DashFlowArea, number>>;
+    /** Services the flow reached. */
+    projects: string[];
+    /** Bumps whenever an event for this flow arrives — refetch the detail when it changes. */
+    rev: number;
+    /** How many requests the flow sent through the gateway (a scripted flow can send many). */
+    requestCount?: number;
+    /** Error-level steps in the flow, and the first one's title — so a list can say WHAT failed. */
+    errorCount?: number;
+    firstError?: string;
+    /**
+     * What the flow touched: `GET /route`, `sql:<project>:<op table>`, `egress:<project>:<host>`.
+     * How a finding that carries no event ids (a slow route, a slow query shape, a failing host)
+     * still finds a flow that shows it.
+     */
+    touches?: string[];
+}
+/**
+ * One display node of a flow — the output of `buildFlowDetail` in `@lensmcp/core`. Every field
+ * beyond the first block is optional: which appear depends on the event kind and on the folds
+ * (fetch pairing, React commits, ×N repetition) the transform applied.
+ */
+export interface DashFlowNode {
+    id: string;
+    t: number;
+    start: number;
+    source: string;
+    category: string;
+    severity: string;
+    title: string;
+    kind?: string;
+    area: DashFlowArea;
+    parent?: string;
+    group?: 'browser' | 'server' | string;
+    requestId?: string;
+    parentRequestId?: string;
+    fetchStartId?: string;
+    fetchDoneId?: string;
+    project?: string;
+    role?: string;
+    queue?: string;
+    jobId?: string;
+    sig?: string;
+    urlKey?: string;
+    durationMs?: number;
+    detail?: string;
+    steps?: string[];
+    ai?: Record<string, unknown>;
+    commitId?: string;
+    component?: string;
+    phase?: string;
+    why?: string[];
+    viewPhase?: 'mount' | 'update';
+    cause?: string;
+    causeComponents?: string[];
+    components?: string[];
+    mounted?: string[];
+    renderCount?: number;
+    recordedRenders?: number;
+    effects?: number;
+    effectHooks?: string[];
+    count?: number;
+    parallel?: boolean;
+    avgMs?: number;
+    wallMs?: number;
+    items?: Array<{
+        start: number;
+        durationMs?: number;
+    }>;
+    memberIds?: string[];
+    selfMs?: number;
+}
+export interface DashFlowDetail {
+    flowId: string;
+    /** The reducer's own summary (kept as-is for older consumers). */
+    summary: unknown;
+    events: DashFlowNode[];
+    /** Same counter as `DashFlowSummary.rev` at the time of the read. */
+    rev?: number;
+}
+export interface DashLogLine {
+    seq: number;
+    at: number;
+    /** The concrete service (pod project) when known, else the event source. */
+    source: string;
+    category: string;
+    severity: string;
+    title: string;
+    message?: string;
+    flowId?: string;
+}
+export interface DashLogsFrame {
+    seq: number;
+    sources: string[];
+    lines: DashLogLine[];
+}
+export type DashProblemSeverity = 'high' | 'medium' | 'low';
+export type DashProblemKind = 'n-plus-one' | 'db-in-loop' | 'render-storm' | 'slow-path' | 'slow-route' | 'slow-query' | 'missing-index' | 'leak' | 'server-error' | 'browser-error' | 'failed-span' | 'egress-failing' | 'egress-slow' | 'duplicate-requests' | 'build' | 'typecheck' | 'lint' | 'service' | 'other';
+export interface DashProblem {
+    /** Stable across updates — the card's identity for the resolved-lifecycle. */
+    id: string;
+    kind: DashProblemKind;
+    severity: DashProblemSeverity;
+    /** What is wrong, in one line. */
+    title: string;
+    /** Where: a route, a query shape, a component, `file:line`. */
+    where?: string;
+    /** Why it matters / the measurement behind it. */
+    detail?: string;
+    /** What to do — only when the detector itself knows; never invented. */
+    fix?: string;
+    /** The concrete artefact: the SQL, the stack's first frames, the failing URL. */
+    code?: string;
+    /** How many times it happened, when the detector counts. */
+    count?: number;
+    /** The flow (and node inside it) that shows this happening. */
+    evidence?: {
+        flowId?: string;
+        nodeId?: string;
+        eventIds?: string[];
+    };
+    /** The resource the finding came from — the Raw drawer opens it. */
+    resource: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** Set once the detector stops reporting it — the "did my fix work?" answer. */
+    resolvedAt?: number;
+}
+export type DashCheckStatus = 'pass' | 'fail' | 'warn' | 'unchecked' | 'stale';
+/** The build/typecheck/lint/browser signal health row — "not watching" is not "passing". */
+export interface DashCheck {
+    id: string;
+    label: string;
+    status: DashCheckStatus;
+    detail: string;
+    resource: string;
+}
+export interface DashMemoryOwner {
+    ownerId: string;
+    itemCount: number;
+    growth: number;
+    mutations: number;
+    lastMutatedAt?: number;
+    suspected: boolean;
+    flowIds: string[];
+}
+export interface DashHotComponent {
+    component: string;
+    renders: number;
+    totalMs: number;
+}
+export interface DashDiagnostics {
+    at: number;
+    problems: DashProblem[];
+    checks: DashCheck[];
+    memory: {
+        heapUsed?: number;
+        rss?: number;
+        owners: DashMemoryOwner[];
+    };
+    react: {
+        hot: DashHotComponent[];
+    };
+}
+/**
+ * server    — a request a service answered with a 5xx / an exception reached its handler
+ * exception — a traced call threw, but the request survived
+ * request   — a request failed before or outside a service (gateway 5xx, browser fetch failure)
+ * browser   — an uncaught error / rejected promise / failed resource in the page
+ * external  — a call to a third-party host failed
+ * queue     — a background job failed
+ * log       — an error-level log line no request explains
+ * build / typecheck / service — the code or a service is broken right now (standing, not events)
+ */
+export type DashErrorKind = 'server' | 'exception' | 'request' | 'browser' | 'external' | 'queue' | 'log' | 'build' | 'typecheck' | 'service';
+export interface DashErrorOccurrence {
+    /** The primary event's id. */
+    id: string;
+    at: number;
+    flowId?: string;
+    /** The deepest failing step inside the flow — where the trace should open. */
+    stepId?: string;
+    requestId?: string;
+    status?: number;
+    /** Only when it differs from the group's message. */
+    message?: string;
+}
+export interface DashErrorGroup {
+    /** Stable signature — the same error, grouped however many times it happens. */
+    id: string;
+    kind: DashErrorKind;
+    /** What failed: `GET /orders/lab/boom → 500`, `Uncaught Error: …`. */
+    title: string;
+    /** Where: the service, host or page. */
+    where?: string;
+    project?: string;
+    message?: string;
+    /** App frames first; framework frames trimmed. */
+    stack?: string;
+    status?: number;
+    count: number;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** Newest first, bounded. */
+    occurrences: DashErrorOccurrence[];
+    /** Distinct flows it happened in. */
+    flowCount: number;
+    /** Occurrences per minute, oldest → newest (last 30 minutes). */
+    spark: number[];
+    /** A standing condition (a broken build, a crashing service) rather than an event. */
+    ongoing?: boolean;
+    /** The resource this came from, for the Raw drawer. */
+    resource?: string;
+}
+export interface DashErrors {
+    at: number;
+    /** What "recent" means below (ms). */
+    recentMs: number;
+    groups: DashErrorGroup[];
+    /** Groups seen within `recentMs` (plus ongoing ones). */
+    recentGroups: number;
+    recentOccurrences: number;
+}
+export interface DashResourceEntry {
+    uri: string;
+    scheme: string;
+    revision?: number;
+}
+export interface DashFlowRev {
+    flowId: string;
+    rev: number;
+}
+/** Every SSE frame on `/api/stream`: the SSE `event:` name is `type`, `data:` is `data`. */
+export type DashStreamEvent = {
+    type: 'hello';
+    data: DashHello;
+} | {
+    type: 'session';
+    data: DashSession;
+} | {
+    type: 'cluster';
+    data: DashCluster;
+} | {
+    type: 'kpis';
+    data: DashKpis;
+} | {
+    type: 'flows';
+    data: {
+        flows: DashFlowSummary[];
+    };
+} | {
+    type: 'flow-rev';
+    data: DashFlowRev[];
+} | {
+    type: 'logs';
+    data: DashLogsFrame;
+}
+/** The server dropped log frames for this client (slow socket) — refetch from `seq`. */
+ | {
+    type: 'logs-resync';
+    data: {
+        seq: number;
+    };
+} | {
+    type: 'diagnostics';
+    data: DashDiagnostics;
+} | {
+    type: 'errors';
+    data: DashErrors;
+};
+export type DashStreamEventType = DashStreamEvent['type'];

package/lib/dashboard.js

@@ -0,0 +1 @@
+"use strict";export const DASHBOARD_PROTOCOL=1;

package/lib/flood-guard.js

@@ -1 +1 @@
-"use strict";var m=Object.defineProperty;var i=(t,n)=>m(t,"name",{value:n,configurable:!0});var v=Object.defineProperty,u=i((t,n)=>v(t,"name",{value:n,configurable:!0}),"o");function p(){const t=typeof process<"u"?process.env?.LENSMCP_EVENT_MAX_EPS:void 0;if(t===void 0||t==="")return;if(t==="off")return"off";const n=Number(t);if(Number.isFinite(n))return n<=0?"off":n}i(p,"S"),u(p,"envPerSec");export function createEventFloodGuard(t){const n=p();if(n==="off")return{admit:u(()=>({ok:!0,suppressed:0}),"admit")};const l=n??t?.perSec??5,f=Math.max(1,t?.burst??Math.max(30,l*4)),c=t?.maxKeys??2048,r=new Map,d=u(o=>{for(const[s,e]of r)o-e.lastSeenAt>6e4&&r.delete(s);if(r.size>c){const s=[...r.entries()].sort((e,a)=>e[1].lastSeenAt-a[1].lastSeenAt);for(let e=0;e<s.length>>1;e++)r.delete(s[e][0])}},"evictStale");return{admit(o){const s=Date.now();let e=r.get(o);e||(r.size>=c&&d(s),e={tokens:f,lastRefillAt:s,suppressed:0,lastSeenAt:s},r.set(o,e)),e.lastSeenAt=s;const a=s-e.lastRefillAt;if(a>0&&(e.tokens=Math.min(f,e.tokens+a/1e3*l),e.lastRefillAt=s),e.tokens>=1){e.tokens-=1;const S=e.suppressed;return e.suppressed=0,{ok:!0,suppressed:S}}return e.suppressed+=1,{ok:!1,suppressed:0}}}}i(createEventFloodGuard,"createEventFloodGuard"),u(createEventFloodGuard,"createEventFloodGuard");
+"use strict";var S=Object.defineProperty;var i=(t,s)=>S(t,"name",{value:s,configurable:!0});var A=Object.defineProperty,f=i((t,s)=>A(t,"name",{value:s,configurable:!0}),"i"),k=Object.defineProperty,u=f((t,s)=>k(t,"name",{value:s,configurable:!0}),"o");function l(){const t=typeof process<"u"?process.env?.LENSMCP_EVENT_MAX_EPS:void 0;if(t===void 0||t==="")return;if(t==="off")return"off";const s=Number(t);if(Number.isFinite(s))return s<=0?"off":s}i(l,"p"),f(l,"S"),u(l,"envPerSec");export function createEventFloodGuard(t){const s=l();if(s==="off")return{admit:u(()=>({ok:!0,suppressed:0}),"admit")};const c=s??t?.perSec??5,d=Math.max(1,t?.burst??Math.max(30,c*4)),p=t?.maxKeys??2048,n=new Map,v=u(o=>{for(const[r,e]of n)o-e.lastSeenAt>6e4&&n.delete(r);if(n.size>p){const r=[...n.entries()].sort((e,a)=>e[1].lastSeenAt-a[1].lastSeenAt);for(let e=0;e<r.length>>1;e++)n.delete(r[e][0])}},"evictStale");return{admit(o){const r=Date.now();let e=n.get(o);e||(n.size>=p&&v(r),e={tokens:d,lastRefillAt:r,suppressed:0,lastSeenAt:r},n.set(o,e)),e.lastSeenAt=r;const a=r-e.lastRefillAt;if(a>0&&(e.tokens=Math.min(d,e.tokens+a/1e3*c),e.lastRefillAt=r),e.tokens>=1){e.tokens-=1;const m=e.suppressed;return e.suppressed=0,{ok:!0,suppressed:m}}return e.suppressed+=1,{ok:!1,suppressed:0}}}}i(createEventFloodGuard,"createEventFloodGuard"),f(createEventFloodGuard,"createEventFloodGuard"),u(createEventFloodGuard,"createEventFloodGuard");

package/lib/producer-health.js

@@ -1 +1 @@
-"use strict";var m=Object.defineProperty;var i=(t,o)=>m(t,"name",{value:o,configurable:!0});var R=Object.defineProperty,p=i((t,o)=>R(t,"name",{value:o,configurable:!0}),"u");import{z as e}from"zod";export const ProducerStateSchema=e.enum(["none","connected"]),ProducerRunStatusSchema=e.enum(["running","clean","failing","error"]),ProducerReportSchema=e.object({id:e.string(),tool:e.string(),project:e.string().optional(),firstReportedAt:e.number().int().nonnegative(),lastReportedAt:e.number().int().nonnegative(),lastRunStatus:ProducerRunStatusSchema,lastRunDurationMs:e.number().int().nonnegative().optional(),errorCount:e.number().int().nonnegative(),warningCount:e.number().int().nonnegative().optional(),error:e.string().optional()}),ProducerHealthSchema=e.object({producer:ProducerStateSchema,producers:e.array(ProducerReportSchema),lastReportedAt:e.number().int().nonnegative().optional(),ageMs:e.number().int().nonnegative().optional(),stale:e.boolean(),detail:e.string()}),PRODUCER_STALE_AFTER_MS=10*6e4;export function summariseProducers(t){const o=t.now??Date.now(),n=[...t.producers].sort((r,h)=>h.lastReportedAt-r.lastReportedAt);if(n.length===0)return{producer:"none",producers:[],stale:!1,detail:`No ${t.domain} producer has ever reported into this session \u2014 this is NOT a clean result, nothing is watching. ${t.noProducerHint}`};const d=n[0].lastReportedAt,u=Math.max(0,o-d),l=u>PRODUCER_STALE_AFTER_MS,c=n.filter(r=>r.lastRunStatus==="failing"),s=n.filter(r=>r.lastRunStatus==="error"),a=[`${n.length} ${t.domain} producer${n.length===1?"":"s"} reporting (${n.map(r=>r.id).join(", ")}); newest report ${g(u)}.`];return s.length>0&&a.push(`${s.length} produced NO verdict (the tool itself failed): ${s.map(r=>`${r.id} \u2014 ${r.error??"unknown error"}`).join("; ")}.`),c.length>0&&a.push(`${c.length} reporting errors.`),l&&a.push(`Older than ${Math.round(PRODUCER_STALE_AFTER_MS/6e4)}m \u2014 the verdict may predate the current source.`),{producer:"connected",producers:n,lastReportedAt:d,ageMs:u,stale:l,detail:a.join(" ")}}i(summariseProducers,"summariseProducers"),p(summariseProducers,"summariseProducers");function g(t){return t<1e3?"just now":t<6e4?`${Math.round(t/1e3)}s ago`:t<36e5?`${Math.round(t/6e4)}m ago`:`${Math.round(t/36e5)}h ago`}i(g,"g"),p(g,"describeAge");
+"use strict";var R=Object.defineProperty;var i=(e,o)=>R(e,"name",{value:o,configurable:!0});var $=Object.defineProperty,d=i((e,o)=>$(e,"name",{value:o,configurable:!0}),"i"),b=Object.defineProperty,m=d((e,o)=>b(e,"name",{value:o,configurable:!0}),"u");import{z as r}from"zod";export const ProducerStateSchema=r.enum(["none","connected"]),ProducerRunStatusSchema=r.enum(["running","clean","failing","error"]),ProducerReportSchema=r.object({id:r.string(),tool:r.string(),project:r.string().optional(),firstReportedAt:r.number().int().nonnegative(),lastReportedAt:r.number().int().nonnegative(),lastRunStatus:ProducerRunStatusSchema,lastRunDurationMs:r.number().int().nonnegative().optional(),errorCount:r.number().int().nonnegative(),warningCount:r.number().int().nonnegative().optional(),error:r.string().optional()}),ProducerHealthSchema=r.object({producer:ProducerStateSchema,producers:r.array(ProducerReportSchema),lastReportedAt:r.number().int().nonnegative().optional(),ageMs:r.number().int().nonnegative().optional(),stale:r.boolean(),detail:r.string()}),PRODUCER_STALE_AFTER_MS=10*6e4;export function summariseProducers(e){const o=e.now??Date.now(),t=[...e.producers].sort((n,h)=>h.lastReportedAt-n.lastReportedAt);if(t.length===0)return{producer:"none",producers:[],stale:!1,detail:`No ${e.domain} producer has ever reported into this session \u2014 this is NOT a clean result, nothing is watching. ${e.noProducerHint}`};const l=t[0].lastReportedAt,u=Math.max(0,o-l),p=u>PRODUCER_STALE_AFTER_MS,g=t.filter(n=>n.lastRunStatus==="failing"),s=t.filter(n=>n.lastRunStatus==="error"),a=[`${t.length} ${e.domain} producer${t.length===1?"":"s"} reporting (${t.map(n=>n.id).join(", ")}); newest report ${c(u)}.`];return s.length>0&&a.push(`${s.length} produced NO verdict (the tool itself failed): ${s.map(n=>`${n.id} \u2014 ${n.error??"unknown error"}`).join("; ")}.`),g.length>0&&a.push(`${g.length} reporting errors.`),p&&a.push(`Older than ${Math.round(PRODUCER_STALE_AFTER_MS/6e4)}m \u2014 the verdict may predate the current source.`),{producer:"connected",producers:t,lastReportedAt:l,ageMs:u,stale:p,detail:a.join(" ")}}i(summariseProducers,"summariseProducers"),d(summariseProducers,"summariseProducers"),m(summariseProducers,"summariseProducers");function c(e){return e<1e3?"just now":e<6e4?`${Math.round(e/1e3)}s ago`:e<36e5?`${Math.round(e/6e4)}m ago`:`${Math.round(e/36e5)}h ago`}i(c,"g"),d(c,"g"),m(c,"describeAge");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/protocol-types",
-  "version": "1.22.5",
+  "version": "1.23.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",