@lensmcp/protocol-types 1.25.5 → 1.25.7

package/index.d.ts

@@ -19,3 +19,5 @@ export * from './lib/ai-content.js';
 export * from './lib/http-exchange.js';
 export * from './lib/pod-memory.js';
 export * from './lib/perf-rules.js';
+export * from './lib/sources.js';
+export * from './lib/page-visit.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";export*from"./lib/dashboard.js";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.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";export*from"./lib/log-query.js";export*from"./lib/error-dismissal.js";export*from"./lib/ai-content.js";export*from"./lib/http-exchange.js";export*from"./lib/pod-memory.js";export*from"./lib/perf-rules.js";export*from"./lib/sources.js";export*from"./lib/page-visit.js";

package/lib/dashboard.d.ts

@@ -11,6 +11,7 @@
  * on-demand GETs.
  */
 import type { HttpExchange } from './http-exchange.js';
+import type { PageVisitNavType, PageVisitRaw, PageVisitReadyBy, PageVisitRequest, PageVisitVitals } from './page-visit.js';
 /** 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). */
@@ -521,6 +522,14 @@ export interface DashFlowDetail {
     segmentStats?: DashSegmentStats;
     /** Present when the read asked for one segment (`?segment=`): `events` then holds only that segment. */
     focus?: DashFlowSegment;
+    /**
+     * Present when the read asked for a time window (`?from=&to=`, epoch ms — a page visit's start and ready): `events`
+     * then holds only the flow's steps inside it, while `segments`/`phases` still describe the whole flow.
+     */
+    window?: {
+        from?: number;
+        to?: number;
+    };
     /**
      * Present when the flow was no longer in the live window and was read back — from the workspace's event history
      * (30 days) or the bus files. `complete: false`: older events of it may be missing.
@@ -656,6 +665,19 @@ export interface DashDiagnostics {
         slow: number;
         warnings: number;
     };
+    /**
+     * Set on the stream's frame, which carries only what a page lists: the findings of a {@link DASH_PERF_KINDS} kind
+     * (failures are the Errors screen's, from `DashErrors`), the open ones and then the recently resolved ones, each up
+     * to a cap. These are their numbers before the cap — `open - problems.filter(open).length` is a list's «N more».
+     * Absent from older servers, whose frame held every problem.
+     */
+    totals?: {
+        open: number;
+        resolved: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
 }
 /** The problem kinds that are "slow or wasteful" — Performance's findings and the slow counter. */
 export declare const DASH_PERF_KINDS: readonly DashProblemKind[];
@@ -742,6 +764,11 @@ export interface DashErrors {
     recentOccurrences: number;
     /** Hidden by hand, and still hidden: nothing of them has been seen since. Listed so they can be restored. */
     dismissed: DashErrorGroup[];
+    /**
+     * Set on the stream's frame: each group carries at most this many `occurrences`, newest first (and the newest with a
+     * flow when none of those has one) — what Errors shows of a group. The error log keeps more; `count` is all of them.
+     */
+    occurrencesShown?: number;
 }
 /** `POST /api/errors/dismiss` and `/api/errors/restore` — the body, and the answer. */
 export interface DashErrorIds {
@@ -798,8 +825,55 @@ export type DashStreamEvent = {
 } | {
     type: 'errors';
     data: DashErrors;
+}
+/** The shell's numbers, on every tab whatever page it shows. */
+ | {
+    type: 'summary';
+    data: DashSummary;
+}
+/** Every 15 s on every connection — what tells a tab its stream is alive when its page's frames are quiet. */
+ | {
+    type: 'ping';
+    data: Record<string, never>;
 };
 export type DashStreamEventType = DashStreamEvent['type'];
+/**
+ * What a tab asks the stream for: `GET /api/stream?topics=cluster,flows` — the frames its page reads. `hello` and
+ * `ping` go to every tab, `summary` too (asked or not); `logs-resync` goes with `logs`, and the log backlog is sent
+ * only to a tab that asks for `logs`. A tab that sends no `topics` gets every frame (a UI from before topics).
+ */
+export type DashStreamTopic = 'summary' | 'session' | 'cluster' | 'kpis' | 'flows' | 'flow-rev' | 'logs' | 'diagnostics' | 'errors';
+export declare const DASH_STREAM_TOPICS: readonly DashStreamTopic[];
+/**
+ * The shell's numbers — the sidebar's badges, the top bar's counters, the scope card — for a tab whose page does not
+ * take the frame they come from. Counted by the same code as those frames, from what their producers last built.
+ * A part is absent until its producer first ran.
+ */
+export interface DashSummary {
+    /** `DashErrors.recentGroups`, and how many groups it lists (`groups.length`). */
+    errors?: {
+        recentGroups: number;
+        groups: number;
+    };
+    /** `DashDiagnostics.counts`, and each warning's title (`warnings[].title`) — the top bar's tooltip. */
+    diagnostics?: {
+        slow: number;
+        warnings: number;
+        warningTitles: string[];
+    };
+    /** Each listed flow's `lastSeenAt`, newest first, as many as `flows` lists: the «new flows» badge counts those after the tab last looked. */
+    flows?: {
+        lastSeenAt: number[];
+    };
+    /** Services down, wedged or crash-looping; and the scope card's `DashCluster.instance` and `worktrees`. */
+    cluster?: {
+        troubled: number;
+        instance?: DashCluster['instance'];
+        worktrees?: DashWorktree[];
+    };
+    /** `DashSession.setupIssues.length`. */
+    setupIssues?: number;
+}
 /**
  * What one run of a route touched, by key, with how many times:
  * `svc:<callee>` a service it called · `ext:<host>` a host outside the cluster · `sql:<VERB> <table>`
@@ -807,15 +881,38 @@ export type DashStreamEventType = DashStreamEvent['type'];
  * `err:<what>` something that threw.
  */
 export type DashTouches = Record<string, number>;
+/**
+ * A run's SQL by its service's own count (node-instrumentation's `db-request-account`): every statement it ran and what
+ * they took, and how many of their events reached the lens. Each statement shape's flood bucket lets only some events
+ * through, so a run's `touches` and `sqlMs` can count a fraction of what it ran — this is the whole of it.
+ */
+export interface DashSqlAccount {
+    statements: number;
+    ms: number;
+    /** Statements whose event reached the lens — what `touches` counts (and session statements, BEGIN and the like). */
+    seen: number;
+    failed?: number;
+    /**
+     * Folded by time, not by the run's own id: a service on a tap from before `runId` that sent several calls under one
+     * request id at once can have had the accounts of two such calls swapped. Their sum is right.
+     */
+    byTime?: true;
+}
 export interface DashRouteRun {
     at: number;
     flowId?: string;
     requestId?: string;
     status?: number;
     durationMs?: number;
+    /** What its SQL statements took, summed (ms) — the statements its `sql:` touches count. */
+    sqlMs?: number;
+    /** Its SQL by its service's own count, when the service sent one — the whole of it, where `touches` may hold a part. */
+    sqlAccount?: DashSqlAccount;
     /** Who called it: another service by name, else `client`. */
     caller?: string;
     touches: DashTouches;
+    /** Its request and response as they came in and went out (an `ingress` exchange, `/api/exchange?id=`). */
+    exchangeId?: string;
 }
 export type DashRouteChangeKind = 'new-external' | 'new-service' | 'new-query' | 'new-queue' | 'new-cache' | 'new-error' | 'gone' | 'gone-error' | 'count' | 'status' | 'duration';
 export interface DashRouteChange {
@@ -1024,6 +1121,201 @@ export interface DashRoutesCatalog {
     /** How far back the kept history reaches. */
     since?: number;
 }
+/** p50 / p95 over a page's kept samples, and how many it has. */
+export interface DashPageStat {
+    p50: number;
+    p95: number;
+    n: number;
+}
+/** One request of a visit, as the browser saw it, joined to the backend's run of it when that was seen. */
+export interface DashPageRequest extends PageVisitRequest {
+    /** The route that answered it (`<service> METHOD /route`, an id of catalog://routes). */
+    routeId?: string;
+    service?: string;
+    /** The server's own status and time. */
+    status?: number;
+    serverMs?: number;
+    /**
+     * SQL statements, and what they took, over its run and the cluster calls it waited on — by the services' own count
+     * where they sent one (`DashRouteRun.sqlAccount`), else what reached the lens.
+     */
+    sql?: number;
+    sqlMs?: number;
+    /** Of `sql`, how many statements' events reached the lens — only where that is fewer. */
+    sqlSeen?: number;
+    /** Key-value commands and calls outside the cluster, over the same runs. */
+    cache?: number;
+    ext?: number;
+    /** Other services' runs under its request id, inside its own run (east-west): how many, and by route (at most 10 routes). */
+    callCount?: number;
+    calls?: Array<{
+        routeId: string;
+        n: number;
+    }>;
+    /** Same method, path and query hash as an earlier request of the visit. */
+    dup?: true;
+}
+/** One visit of a page, in a few hundred bytes — the requests in full only on the newest two and the slowest. */
+export interface DashPageVisit {
+    visitId: string;
+    tabId?: string;
+    /** The pathname it opened. */
+    path: string;
+    nav: 'hard' | 'spa';
+    navType?: PageVisitNavType;
+    cause?: 'hmr';
+    redirectedFrom?: string;
+    /** The page the tab showed before (an SPA navigation): its pattern, or its path when it had none. */
+    from?: string;
+    startAt: number;
+    readyAt?: number;
+    readyBy?: PageVisitReadyBy;
+    readyMs?: number;
+    appReadyMs?: number;
+    endAt?: number;
+    flowIds: string[];
+    /** Requests it made until ready, with those past the 60 the browser lists. */
+    requests: number;
+    /** Of the listed ones, how many were joined to their backend run. */
+    joined: number;
+    /** Requests whose run has not been seen yet — joined as it arrives, given up two minutes after the visit. */
+    waiting?: number;
+    /** The same request made again in the visit (method, path and query hash). */
+    duplicates: number;
+    /** Over its joined requests (`DashPageRequest.sql`). */
+    sql: number;
+    sqlMs: number;
+    /** Of `sql`, how many statements' events reached the lens — only where that is fewer. */
+    sqlSeen?: number;
+    /** The joined requests by the service that answered them. */
+    services?: Record<string, number>;
+    commits: number;
+    renders: number;
+    renderMs: number;
+    maxCommitMs: number;
+    stormCommits: number;
+    suspenseWaits: number;
+    updates: number;
+    errors: number;
+    firstError?: string;
+    /** A request answered 5xx, the page threw, or it was never ready (`timeout`). */
+    failed?: true;
+    afterReady?: PageVisitRaw['afterReady'];
+    vitals?: PageVisitVitals;
+    longTasks?: PageVisitRaw['longTasks'];
+    heapMb?: number;
+    chunks?: PageVisitRaw['chunks'];
+    /** Its requests in full — kept for the newest two visits and the slowest. */
+    requestList?: DashPageRequest[];
+}
+/** A request the page makes, over its kept visits: `METHOD /path` with ids folded. */
+export interface DashPageUse {
+    template: string;
+    method: string;
+    path: string;
+    host?: string;
+    /** The backend route that answers it, once a run of it was joined. */
+    routeId?: string;
+    /** In how many visits, and how often per visit that made it. */
+    inVisits: number;
+    perVisit: number;
+    /** The browser's time to its response headers. */
+    p50?: number;
+    /** Calls that answered 4xx/5xx or failed on the network. */
+    failed: number;
+    /** Calls that repeated an earlier one of their visit (same method, path and query hash). */
+    duplicates: number;
+    /** SQL statements per joined call, on average. */
+    sqlPerCall?: number;
+    /** Made by the latest visit. */
+    latest: boolean;
+}
+export type DashPageChangeKind = 'new-request' | 'gone-request' | 'status' | 'failed' | 'count' | 'sql' | 'duration';
+export interface DashPageChange {
+    kind: DashPageChangeKind;
+    /** The request template it is about, when it is about one. */
+    key?: string;
+    /** One line: "now requests GET /api/orders/:id", "GET /api/x ×1 → ×3", "SQL 12 → 31 statements", "ready 420 ms → 1,310 ms". */
+    text: string;
+}
+export interface DashPageSummary {
+    /** `<app> <pattern>`. */
+    id: string;
+    /** Its newest finished page review — none until the `page` review exists (planning/pages S6). */
+    review?: DashReviewMark;
+    /** The app the Vite plugin serves (or the page's host). */
+    app: string;
+    /** The router's full match pattern. */
+    pattern: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    visits: number;
+    hard: number;
+    spa: number;
+    /** Hard loads the dev server's hot reload caused: listed, kept out of every sample. */
+    hmr: number;
+    errors: number;
+    failedVisits: number;
+    /** Ready per population: SPA visits from the navigation (`readyMs`), hard loads from the app's entry (`appReadyMs`). */
+    ready: {
+        spa?: DashPageStat;
+        hard?: DashPageStat;
+    };
+    /** Per visit: requests, SQL statements and ms, renders and render ms, store updates. */
+    perVisit: Partial<Record<'requests' | 'sql' | 'sqlMs' | 'renders' | 'renderMs' | 'updates', DashPageStat>>;
+    /** The latest visit — not a hot reload, unless the page has nothing else — without its request list. */
+    last?: DashPageVisit;
+    /** Where its SPA visits came from (the tab's page before), most often first; at most 3. */
+    from: Array<{
+        page: string;
+        n: number;
+    }>;
+    /** The latest visit against the one before — hot reloads left out. */
+    changes: DashPageChange[];
+}
+export interface DashPageDetail extends DashPageSummary {
+    /** Newest first, at most 20; the newest two carry `requestList`. */
+    recent: DashPageVisit[];
+    /** The slowest visit kept (by its population's ready), with its requests. */
+    slowest?: DashPageVisit;
+    /** What it requests, most visits first; at most 50. */
+    uses: DashPageUse[];
+    /** The most-rendered components, over the visits that reported them; at most 20. */
+    components: Array<{
+        name: string;
+        n: number;
+        ms: number;
+        inVisits: number;
+    }>;
+    /** The most-updated store paths; at most 20. */
+    store: Array<{
+        store: string;
+        path: string;
+        n: number;
+        inVisits: number;
+    }>;
+    /** Real paths that took this pattern, newest first; at most 10. */
+    paths: string[];
+}
+/** Visits with no router pattern, by app and templated path: not pages (planning/hub decision 9). */
+export interface DashPageUnmatched {
+    app: string;
+    path: string;
+    visits: number;
+    lastSeenAt: number;
+}
+export interface DashPagesCatalog {
+    at: number;
+    /** Most recently seen first. */
+    pages: DashPageSummary[];
+    /** At most 50 paths; `visits` sums them. */
+    unmatched: {
+        visits: number;
+        paths: DashPageUnmatched[];
+    };
+    /** How far back the kept visits reach. */
+    since?: number;
+}
 /** What one AI model was asked through an endpoint, and what it cost in tokens. */
 export interface DashAiUse {
     model: string;
@@ -1051,8 +1343,13 @@ export interface DashExternalCall {
     /** The request it was made in — the calls that share it are one request's steps. */
     requestId?: string;
 }
-/** One call opened (Data › External APIs' Request & response panel): the call, its exchange, its request's other steps. */
+/**
+ * One exchange opened in the Request & response panel: an outbound call (Data › External APIs, a flow's step) or a
+ * route's run (Routes › a route › Runs) — the call or the run, its exchange, its request's other steps.
+ */
 export interface DashExchangeView {
+    /** What was opened: an outbound call (`host` is its host), or a route's run (`host` is the service that served it). */
+    of?: 'call' | 'run';
     host: string;
     call: DashExternalCall;
     /** Absent: not captured (capture off, headers rotated away) or withheld (`withheld` says why). */
@@ -1166,6 +1463,14 @@ export interface DashSqlFinding {
     tool: string;
     at: number;
 }
+/**
+ * Why a statement is test SQL: every site it ran from is a test file (`sites`), its name starts with `test.` (`name`), or
+ * nx.json → `lensmcp.sql.test` lists it (`listed`).
+ */
+export interface DashSqlTestMark {
+    by: 'sites' | 'name' | 'listed';
+    why: string;
+}
 /**
  * A place in the services' own code where something ran — what a coding agent opens. From the stack the tap took at
  * the call: the service's nearest frame, and the callers above it.
@@ -1210,6 +1515,8 @@ export interface DashSqlTemplateSummary {
     sites?: DashCodeSite[];
     /** An unnamed statement its named version replaced (edited as it was named): that statement's id — not one to name. */
     replacedBy?: string;
+    /** Test SQL — written in a test, not in the services' code (apps/catalog sql-test.ts): not linted, named or reviewed by itself. */
+    test?: DashSqlTestMark;
     /** SELECT · INSERT · UPDATE · DELETE · …; a WITH reads as the statement it leads to. */
     verb: string;
     tables: string[];
@@ -1396,9 +1703,50 @@ export interface DashDbSchema {
         rows: DashDbStatementStat[];
     };
     findings: DashDbFinding[];
+    /** What the findings judged — and what a size floor left out, so «no finding» is not read as «nothing there». */
+    checked?: DashDbChecked;
     /** A read that failed, in Postgres's words. */
     error?: string;
 }
+/** One database's last read by LensMCP's own checks (`db.schema`), as `db://analysis` names it beside the analyzer's runs. */
+export interface DashDbChecksSeen {
+    store: string;
+    database: string;
+    at: number;
+    findings: number;
+    byKind: Partial<Record<DashDbFinding['kind'], number>>;
+    /** {@link DashDbChecked.note}: what the checks judged. */
+    judged?: string;
+}
+/**
+ * What LensMCP's own checks of a database judged (foodguard-83). The table checks (seq-scan, dead-rows,
+ * unindexed-foreign-key) judge only tables of `floorRows` rows or more — on a development database that is often none.
+ */
+export interface DashDbChecked {
+    tables: number;
+    /** Tables at or over the floor: the ones the table checks judged. */
+    judged: number;
+    floorRows: number;
+    /** Under the floor, the most sequentially scanned — not judged, named so the floor hides nothing. */
+    belowFloor: Array<{
+        table: string;
+        rows: number;
+        seqScans: number;
+    }>;
+    indexes: number;
+    /**
+     * Foreign keys no valid index leads with; of those, the ones the check judged (a big child, a parent with deletes),
+     * and the ones under the floor whose referenced table has deletes — a cost once the child grows.
+     */
+    foreignKeys?: {
+        total: number;
+        unindexed: number;
+        judged: number;
+        atScale: number;
+    };
+    /** The above in a sentence. */
+    note: string;
+}
 export interface DashDbTableInfo {
     schema: string;
     name: string;
@@ -1430,6 +1778,8 @@ export interface DashDbIndex {
     valid: boolean;
     /** Part of a partitioned table's index (or that index itself): changed on the parent, never on its own. */
     partition?: boolean;
+    /** The primary key, unique or exclusion constraint it backs — dropping it drops the constraint. */
+    constraint?: string;
     scans: number;
     rowsRead: number;
     bytes: number;
@@ -1665,7 +2015,7 @@ export interface DashDbStatementStat {
     hitRatio?: number;
 }
 export interface DashDbFinding {
-    kind: 'unused-index' | 'duplicate-index' | 'invalid-index' | 'seq-scan' | 'dead-rows';
+    kind: 'unused-index' | 'duplicate-index' | 'invalid-index' | 'seq-scan' | 'dead-rows' | 'unindexed-foreign-key';
     severity: 'high' | 'medium' | 'low';
     table: string;
     index?: string;
@@ -1673,6 +2023,25 @@ export interface DashDbFinding {
     detail: string;
     /** The statement that would fix it — shown to copy, never run by the lens. */
     fix?: string;
+    /** An index finding: the index's own scans and size. */
+    scans?: number;
+    bytes?: number;
+    /** duplicate-index: the index that stays, and why it is enough (`backs <constraint>`, `unique`, `wider`, `the same`). */
+    kept?: {
+        index: string;
+        why: string;
+        scans: number;
+        bytes: number;
+    };
+    /** The table's inserts + updates since Postgres began counting — each index costs a write on every one. */
+    writes?: number;
+    /** unindexed-foreign-key: the constraint, and the table it references. */
+    foreignKey?: {
+        name: string;
+        columns: string[];
+        references: string;
+        onDelete: string;
+    };
 }
 /** One Redis command by its shape: the command and its key with ids folded (`GET session:*`); a script by its hash. */
 export interface DashKvCommandShape {
@@ -1926,12 +2295,18 @@ export interface DashAiAnalyzer {
     folder?: string;
     /** Its runs in this checkout. */
     runs: number;
+    /**
+     * LensMCP's guide it reviews by. `/api/ai/analyzers` leaves its `text` out and says its length (`chars`):
+     * `/api/ai/analyzers/guide?id=` ({@link DashAiAnalyzerGuide}) returns it when Settings shows it — six guides and
+     * six previews in every list were 1 MB a read (FoodGuard, 2026-10-20).
+     */
     guide?: {
         id: string;
         title: string;
         version: number;
         sha: string;
-        text: string;
+        text?: string;
+        chars?: number;
     };
     indicators: Array<{
         id: string;
@@ -1954,10 +2329,14 @@ export interface DashAiAnalyzer {
         path: string;
         why: string;
     }>;
-    /** The instructions every run of it sends now, before the evidence. */
+    /**
+     * The instructions every run of it sends now, before the evidence: their size in the list (`tokens`, `chars`); the
+     * text itself (`system`) from `/api/ai/analyzers/guide?id=`, like the guide's.
+     */
     preview: {
-        system: string;
+        system?: string;
         tokens: number;
+        chars?: number;
     };
     lastRun?: {
         at: number;
@@ -1978,6 +2357,21 @@ export interface DashAiAnalyzer {
         model: string;
     };
 }
+/** `GET /api/ai/analyzers/guide?id=<analyzer>`: one analyzer's guide and what a run of it sends — fetched when Settings shows them. */
+export interface DashAiAnalyzerGuide {
+    id: string;
+    guide?: {
+        id: string;
+        title: string;
+        version: number;
+        sha: string;
+        text: string;
+    };
+    preview: {
+        system: string;
+        tokens: number;
+    };
+}
 /** How hard a frontier model thinks (Claude 4.6 and later; other models are sent none). */
 export type DashAiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export interface DashAiAnalyzers {
@@ -2045,8 +2439,13 @@ export interface DashAiRun {
     analyzerName: string;
     question: string;
     /** What was reviewed; `name` is a statement's name (its leading comment) — the same across its versions. */
+    /**
+     * `db`: one database (`<store>/<database>`, the health check); `dbtable`: one table (`<store>/<database>/<schema>.<table>`);
+     * `kvstore` / `queuestore`: one Redis store's keys / BullMQ queues (`<store>`); `files`: the services' file access
+     * (`files`); `external`: the external APIs the services call (`external`); `log`: one log line (its `seq`).
+     */
     target: {
-        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue';
+        kind: 'sql' | 'route' | 'error' | 'flow' | 'ui' | 'kv' | 'queue' | 'db' | 'dbtable' | 'kvstore' | 'queuestore' | 'files' | 'external' | 'log' | 'page';
         id: string;
         label: string;
         name?: string;
@@ -2144,7 +2543,13 @@ export interface DashAiRun {
         instructions: string;
     };
     error?: string;
+    /**
+     * The run was never sent, so nothing was reviewed: no key could pay (`no-key`), the trigger's daily allowance was
+     * spent (`over-daily-cap`), or every key was out of rate-limit room (`no-room`). A refusal, not a failed review.
+     */
+    refused?: DashAiRefusal;
 }
+export type DashAiRefusal = 'no-key' | 'over-daily-cap' | 'no-room';
 /**
  * An analysis running or waiting now, in the workspace's shared queue: one per `key` (the analyzer and its target),
  * at most the workspace's limit running together, the rest waiting in the order they came.
@@ -2230,11 +2635,12 @@ export interface DashReviewStatus {
         turns?: number;
         tools?: number;
     };
-    /** The newest run, when it failed: when, and its error. */
+    /** The newest run, when it failed: when, and its error — `refused` when it was never sent (DashAiRun.refused). */
     failed?: {
         runId: string;
         at: number;
         error: string;
+        refused?: DashAiRefusal;
     };
 }
 /** A finished review in a few lines: when, its score, what it is about, the changes it asks for first. */

package/lib/dashboard.js

@@ -1 +1 @@
-"use strict";export const DASHBOARD_PROTOCOL=1,DASH_PERF_KINDS=["n-plus-one","db-in-loop","render-storm","slow-path","slow-route","slow-query","missing-index","leak","egress-slow","duplicate-requests","perf-rule","db-connection","other"],DASH_AI_TRIGGERS=["auto","click","agent"];
+"use strict";export const DASHBOARD_PROTOCOL=1,DASH_PERF_KINDS=["n-plus-one","db-in-loop","render-storm","slow-path","slow-route","slow-query","missing-index","leak","egress-slow","duplicate-requests","perf-rule","db-connection","other"],DASH_STREAM_TOPICS=["summary","session","cluster","kpis","flows","flow-rev","logs","diagnostics","errors"],DASH_AI_TRIGGERS=["auto","click","agent"];

package/lib/http-exchange.d.ts

@@ -1,5 +1,6 @@
 /**
- * One HTTP exchange the lens captured (R6): a service's outbound call as it went over the wire — its request and
+ * One HTTP exchange the lens captured (R6): a service's outbound call (`egress`), or a request it served (`ingress`
+ * — a route's run, as it came in and went out), as it went over the wire — its request and
  * response headers (redacted), the query string and the bodies (redacted, the first 64 KB of each), and for a
  * server-sent-events response every event with the moment it arrived. Kept OFF the bus, one file per exchange under
  * `.lensmcp/http/`; the bus event carries its `exchangeId`. Capture: `LENSMCP_HTTP_CAPTURE=off | headers | bodies`.
@@ -17,8 +18,11 @@ export interface HttpExchangeBody {
     /** A binary body: its digest instead of its bytes (when it was small enough to hash). */
     sha256?: string;
     truncated: boolean;
-    /** Why there is no text: `binary`, `form-data`, `stream` (a request body sent as a stream), `ai`. */
-    omitted?: 'binary' | 'form-data' | 'stream' | 'ai';
+    /**
+     * Why there is no text: `binary`, `form-data`, `stream` (a request body sent as a stream), `ai`, `encoded` (a
+     * compressed answer too big to unpack).
+     */
+    omitted?: 'binary' | 'form-data' | 'stream' | 'ai' | 'encoded';
 }
 export interface HttpExchangeStreamEvent {
     /** Since the request started. */
@@ -32,7 +36,7 @@ export interface HttpExchange {
     schemaVersion: 1;
     id: string;
     capturedAt: number;
-    side: 'egress';
+    side: 'egress' | 'ingress';
     service?: string;
     flowId?: string;
     requestId?: string;

package/lib/page-visit.d.ts

@@ -0,0 +1,136 @@
+/**
+ * A page visit, as the browser measures it (planning/pages/00-plan.md §2): from navigation start (a hard load) or a
+ * pathname change (an SPA navigation) to "ready" — the first commit after the page's own requests settle — and on to
+ * its end (the next visit, `pagehide`, or a minute after ready). A visit is not a flow: it records the flows its work
+ * ran under. The tab sends one event when the visit is ready (`phase: 'ready'`) and one when it ends (`phase: 'end'`);
+ * the lens joins its requests to the backend's routes and SQL by request id and folds it into the page catalog.
+ *
+ * Field names stay clear of the redactor's secret words (key, code, session, token …): it would blank their values.
+ * No query string is ever sent — a request names its pathname and a hash of its query.
+ */
+export declare const PAGE_VISIT_KIND: "page-visit";
+/** How the visit began. A hard load: the navigation's type; an SPA navigation: the history call. */
+export type PageVisitNavType = 'navigate' | 'reload' | 'back_forward' | 'push' | 'replace' | 'pop';
+/**
+ * How ready was decided: `settled` — the first commit after the page's requests settled, with none started within the
+ * quiet window; `no-requests` — it made none (the first commit that held); `no-commit` — the requests settled and
+ * nothing committed within a second after (the last commit before); `timeout` — not ready within the cap (its open
+ * requests are named); `left` — the next visit began first.
+ */
+export type PageVisitReadyBy = 'settled' | 'no-requests' | 'no-commit' | 'timeout' | 'left';
+/** One request the page made during the visit (every `fetch`, with or without a flow). */
+export interface PageVisitRequest {
+    /** The request id the lens's fetch hook stamped (`x-request-id`): what the backend's server-request carries. */
+    rid: string;
+    /** Method. */
+    m: string;
+    /** Host + pathname (no query): `api.foodguard.localhost/registry/v1/business-profile/situation-state`. */
+    p: string;
+    /** A short hash of the query string, so two calls with different queries tell apart — never the query. */
+    qh?: string;
+    /** When it started, in ms after the visit's start. */
+    s: number;
+    /** Ms until its response headers (a streamed body does not count); absent while still open. */
+    d?: number;
+    /** HTTP status; 0 for a network failure. */
+    st?: number;
+    /** The flow the request ran under, if one was open. */
+    flowId?: string;
+    /** Started after ready (polling, a lazy panel). */
+    late?: true;
+}
+export interface PageVisitRenders {
+    commits: number;
+    /** Components rendered, summed over the commits. */
+    renders: number;
+    /** React's own render time (actualDuration), summed. */
+    renderMs: number;
+    maxCommitMs: number;
+    /** Commits that rendered more than the storm threshold. */
+    stormCommits: number;
+    mounts: number;
+    /** Commits that showed a Suspense fallback (a lazy chunk or data still loading). */
+    suspenseWaits: number;
+    /** The most-rendered components, by renders: name, renders, ms. At most 8. */
+    top: Array<{
+        name: string;
+        n: number;
+        ms: number;
+    }>;
+}
+export interface PageVisitStore {
+    updates: number;
+    /** The most-updated store paths. At most 8. */
+    top: Array<{
+        store: string;
+        path: string;
+        n: number;
+    }>;
+}
+/** The browser's own timings of a hard load (Web Vitals and friends) — on a Vite dev server, not a production build. */
+export interface PageVisitVitals {
+    ttfb?: number;
+    fcp?: number;
+    lcp?: number;
+    cls?: number;
+    inp?: number;
+    dcl?: number;
+    load?: number;
+}
+export interface PageVisitRaw {
+    kind: typeof PAGE_VISIT_KIND;
+    phase: 'ready' | 'end';
+    visitId: string;
+    /** The browser tab (the client runtime's id), so a tab's visits read in order. */
+    tabId?: string;
+    /** The app the Vite plugin serves (its project name), or the page's host. */
+    app: string;
+    /** The router's full match pattern (`/companies/:id/onboarding/chat`) — absent when no router pattern is known. */
+    pattern?: string;
+    /** The pathname the visit opened (≤ 200 characters, no query). */
+    path: string;
+    nav: 'hard' | 'spa';
+    navType?: PageVisitNavType;
+    /** A hard load the dev server's hot reload caused. */
+    cause?: 'hmr';
+    /** The pathname a `replace` before ready came from (a redirect): the visit went on. */
+    redirectedFrom?: string;
+    /** Epoch ms: navigation start (hard) or the history call (SPA). */
+    startAt: number;
+    readyAt?: number;
+    readyBy?: PageVisitReadyBy;
+    /** Ms from start to ready. */
+    readyMs?: number;
+    /** A hard load: ms from the app's entry module to ready — what the app took, without the dev server serving it. */
+    appReadyMs?: number;
+    endAt?: number;
+    /** The flows the visit's work ran under. */
+    flowIds: string[];
+    /** Up to 60 requests; the rest counted. */
+    requests: PageVisitRequest[];
+    requestsDropped?: number;
+    renders: PageVisitRenders;
+    store: PageVisitStore;
+    errors: {
+        n: number;
+        first?: string;
+    };
+    /** From ready to the end (the `end` event only). */
+    afterReady?: {
+        requests: number;
+        templates: string[];
+        renders: number;
+        updates: number;
+    };
+    vitals?: PageVisitVitals;
+    longTasks?: {
+        n: number;
+        totalMs: number;
+        maxMs: number;
+    };
+    heapMb?: number;
+    chunks?: {
+        n: number;
+        kb: number;
+    };
+}

package/lib/page-visit.js

@@ -0,0 +1 @@
+"use strict";export const PAGE_VISIT_KIND="page-visit";

package/lib/sources.d.ts

@@ -0,0 +1,225 @@
+/**
+ * CUSTOM SOURCES (issues/open/foodguard-81) — an application REPORTS what the lens cannot observe, as one of a closed
+ * set of typed kinds the lens knows how to draw, threshold and explain to an agent: `queue` · `loop` · `store` ·
+ * `traffic`. Phase 1 reads `queue` only — work a service keeps waiting in its OWN storage (an outbox table), which no
+ * event stream can show: FoodGuard's lens showed its BullMQ queues nearly empty while 6,389 outbox rows waited.
+ *
+ * Three hops, each with its own shape:
+ *
+ *  1. The WIRE — the snapshot a service answers on the dev route it declares in project.json (`cluster.sources`):
+ *     `{ schema: 'lensmcp.queue/v1', at, truncated?: { groups }, groups: [{ key, labels?, pending, inFlight?, failed?,
+ *     oldestPendingAt?, completedInWindow? }] }`. The service owns its query; the lens never connects to an app's
+ *     database. `@lensmcp/cluster` parses it (`source-poller.ts`) — a snapshot that does not parse is `malformed`, never
+ *     zero.
+ *  2. The BUS — the gateway's poller reports each poll as a `source: 'gateway'`, `category: 'cluster'` event whose
+ *     `raw.kind` is `source-poll` ({@link SourcePollRaw}), and each service's declaration as `source-declaration`
+ *     ({@link SourceDeclarationRaw}). A group's `key` travels as `group`: the bus redacts any field NAMED `key`
+ *     (`@lensmcp/core` `isSecretParam`), which would have turned every group into `[REDACTED]`. The cluster MIRRORS
+ *     these shapes (it does not depend on this package); a parity fixture pins both sides.
+ *  3. The READ — `apps/agent` folds them into `process://sources` ({@link SourcesReport}); the `observe.sources` and
+ *     `source.get` tools, the status signal and the dashboard read that.
+ *
+ * Everything here is REPORTED by the app, never measured by the lens: every read carries `provenance: 'reported'`.
+ * Additive only.
+ */
+/** The closed set of source kinds. */
+export declare const SOURCE_KINDS: readonly ["queue", "loop", "store", "traffic"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+/** The kinds this release reads; a declared kind outside it is said, not polled. */
+export declare const SOURCE_KINDS_READ: readonly ["queue"];
+export type SourceKindRead = (typeof SOURCE_KINDS_READ)[number];
+/** Every snapshot's schema: `lensmcp.<kind>/v1`. */
+export declare const sourceWireSchema: (kind: SourceKind) => string;
+export declare const QUEUE_WIRE_SCHEMA = "lensmcp.queue/v1";
+/** The resource the lens folds the polls into. */
+export declare const URI_SOURCES = "process://sources";
+/** Said on every read of a source: the app's claim, not the lens's measurement. */
+export declare const SOURCE_PROVENANCE: "reported";
+/** The finding's rule id: a queue group whose oldest pending item has waited longer than `thresholds.oldestWaitMin`. */
+export declare const QUEUE_OLDEST_WAIT_RULE = "queue/oldest-wait";
+export declare const SOURCE_EVENT_KINDS: readonly ["source-poll", "source-declaration"];
+export type SourceEventKind = (typeof SOURCE_EVENT_KINDS)[number];
+/** What ONE poll found. */
+export declare const SOURCE_POLL_STATES: readonly ["current", "unreachable", "refused", "malformed", "not-running"];
+export type SourcePollState = (typeof SOURCE_POLL_STATES)[number];
+/**
+ * What the lens says of a source when it is READ: a poll's state; `stale` — its newest report is overdue (the gateway
+ * stopped polling, or its polls are held up), so whatever it last said is no longer known; or `never-polled` —
+ * declared, and no poll has reported yet.
+ */
+export declare const SOURCE_STATES: readonly ["current", "unreachable", "refused", "malformed", "not-running", "stale", "never-polled"];
+export type SourceState = (typeof SOURCE_STATES)[number];
+export declare const SOURCE_DEFAULT_INTERVAL_SEC = 10;
+export declare const SOURCE_MIN_INTERVAL_SEC = 2;
+export declare const QUEUE_DEFAULT_OLDEST_WAIT_MIN = 10;
+/** A snapshot holds at most this many groups; a producer with more caps it and says `truncated: { groups }`. */
+export declare const SOURCE_MAX_GROUPS = 500;
+export declare const SOURCE_MAX_BYTES: number;
+/** A report is overdue — `stale` — once it is this many report periods old (and never sooner than 30 s). */
+export declare const SOURCE_STALE_PERIODS = 3;
+export declare const SOURCE_STALE_MIN_MS = 30000;
+/** When a source's newest report stops being trusted. */
+export declare function sourceStaleAfterMs(reportEveryMs: number): number;
+/** A queue source's thresholds. `stalledMin` is accepted now and judged once the lens keeps a history (phase 2). */
+export interface QueueThresholds {
+    oldestWaitMin: number;
+    stalledMin?: number;
+}
+/** One declared source, as the gateway polls it. */
+export interface SourceDeclRaw {
+    sourceKind: SourceKindRead;
+    name: string;
+    path: string;
+    intervalSec: number;
+    thresholds: QueueThresholds;
+}
+/** One group of a queue snapshot, as the bus carries it. */
+export interface QueueGroupRaw {
+    /** The service's own key for the group (`tenant/kind`) — the wire's `key`. */
+    group: string;
+    labels?: Record<string, string>;
+    pending: number;
+    inFlight?: number;
+    failed?: number;
+    /** When the oldest pending item of the group was written (ISO). `null`/absent: the service did not say. */
+    oldestPendingAt?: string | null;
+    completedInWindow?: number;
+}
+export interface QueueTotals {
+    groups: number;
+    pending: number;
+    inFlight: number;
+    failed: number;
+    /** Present when any group said it. */
+    completedInWindow?: number;
+}
+/** A queue snapshot that parsed. */
+export interface QueueSnapshotRaw {
+    /** When the SERVICE measured it (its `at`, ISO) — a group's wait is measured at this time. */
+    at: string;
+    /** When the gateway received it (epoch ms) — the snapshot's age is measured from this. */
+    receivedAt: number;
+    totals: QueueTotals;
+    /** Every group the service answered (at most {@link SOURCE_MAX_GROUPS}), the oldest-waiting first. */
+    groups: QueueGroupRaw[];
+    /** The service capped its answer: this many groups were dropped, and are in no total. */
+    truncated?: {
+        groups: number;
+    };
+}
+/** One poll of one declared source (`raw.kind: 'source-poll'`). */
+export interface SourcePollRaw extends SourceDeclRaw {
+    kind: 'source-poll';
+    provenance: typeof SOURCE_PROVENANCE;
+    /** The Nx project that declares it. */
+    project: string;
+    state: SourcePollState;
+    /** Why, for every state but `current`: the error, the status line, what did not parse, why the service was not asked. */
+    detail?: string;
+    /** The HTTP status of a `refused` answer. */
+    status?: number;
+    polledAt: number;
+    durationMs?: number;
+    /** The gateway reports this source again within this many ms — what decides when the lens calls it `stale`. */
+    reportEveryMs: number;
+    /** Polls in a row that failed (`unreachable`/`refused`/`malformed`) — the gateway backs off while it grows. */
+    failures?: number;
+    /** The LAST GOOD snapshot: this poll's when `current`, else the one before (kept, with its age), if any. */
+    snapshot?: QueueSnapshotRaw;
+    /** The owning workspace (stamped by the gateway on every service event). */
+    wsKey?: string;
+    floodSuppressed?: number;
+}
+/** A service's `cluster.sources`, as the gateway read it (`raw.kind: 'source-declaration'`). */
+export interface SourceDeclarationRaw {
+    kind: 'source-declaration';
+    project: string;
+    /** The entries it polls. */
+    sources: SourceDeclRaw[];
+    /** Each entry it does NOT poll, and why — an unknown kind or a malformed entry is said, never silently dropped. */
+    problems: string[];
+    wsKey?: string;
+}
+/** A `source-poll` event's `raw`, checked just enough to be read safely (telemetry is only partly trusted). */
+export declare function asSourcePollRaw(raw: unknown): SourcePollRaw | undefined;
+/** A `source-declaration` event's `raw`, checked just enough to be read safely. */
+export declare function asSourceDeclarationRaw(raw: unknown): SourceDeclarationRaw | undefined;
+/** One queue group, as the lens shows it. */
+export interface QueueGroupView extends QueueGroupRaw {
+    /** How long its oldest pending item had waited when the service measured it (`at − oldestPendingAt`). */
+    oldestWaitMs?: number;
+    /** That wait is longer than the source's `thresholds.oldestWaitMin`. */
+    overThreshold: boolean;
+}
+/** A queue source's headline numbers. */
+export interface QueueHeadline extends QueueTotals {
+    /** The longest wait among its groups, as of the snapshot. */
+    oldestWaitMs?: number;
+    /** Groups whose oldest wait is over the threshold. */
+    overThreshold: number;
+}
+/** One declared source, as the lens shows it. */
+export interface SourceView extends SourceDeclRaw {
+    provenance: typeof SOURCE_PROVENANCE;
+    project: string;
+    state: SourceState;
+    /** Why, for every state but `current`. */
+    detail?: string;
+    status?: number;
+    /** When the gateway last polled it (absent: `never-polled`). */
+    polledAt?: number;
+    failures?: number;
+    /** The last good snapshot's age — present whenever one is held, whatever the state. */
+    ageMs?: number;
+    /** When the service measured the last good snapshot (its `at`). */
+    snapshotAt?: string;
+    headline?: QueueHeadline;
+    /** The oldest-waiting first. Empty with `state: 'current'` is a real «nothing pending». */
+    groups: QueueGroupView[];
+    truncated?: {
+        groups: number;
+    };
+}
+/** A queue group whose oldest pending item has waited longer than its source allows. */
+export interface SourceFinding {
+    rule: typeof QUEUE_OLDEST_WAIT_RULE;
+    provenance: typeof SOURCE_PROVENANCE;
+    project: string;
+    name: string;
+    sourceKind: SourceKindRead;
+    group: string;
+    labels?: Record<string, string>;
+    pending: number;
+    oldestWaitMs: number;
+    thresholdMin: number;
+    title: string;
+    fix: string[];
+    verify: string;
+}
+/** `process://sources`. */
+export interface SourcesReport {
+    schemaVersion?: string;
+    revision?: number;
+    updatedAt?: string;
+    provenance: typeof SOURCE_PROVENANCE;
+    /** `none` until a service declares a source: nothing reports what the taps cannot see — not «nothing waits». */
+    producer: 'connected' | 'none';
+    detail?: string;
+    /** The clock every age here was measured against. */
+    readAt: number;
+    sources: SourceView[];
+    /** Groups over their threshold, from `current` snapshots — the longest wait first. */
+    findings: SourceFinding[];
+    /** Declaration entries the gateway does not poll, and why. */
+    problems: Array<{
+        project: string;
+        problem: string;
+    }>;
+    counts: Record<SourceState, number>;
+    /** Over the `current` queue snapshots only. */
+    totals: {
+        pending: number;
+        inFlight: number;
+        failed: number;
+    };
+}

package/lib/sources.js

@@ -0,0 +1 @@
+"use strict";var E=Object.defineProperty;var n=(r,t)=>E(r,"name",{value:t,configurable:!0});var f=Object.defineProperty,e=n((r,t)=>f(r,"name",{value:t,configurable:!0}),"n");export const SOURCE_KINDS=["queue","loop","store","traffic"],SOURCE_KINDS_READ=["queue"],sourceWireSchema=e(r=>`lensmcp.${r}/v1`,"sourceWireSchema"),QUEUE_WIRE_SCHEMA="lensmcp.queue/v1",URI_SOURCES="process://sources",SOURCE_PROVENANCE="reported",QUEUE_OLDEST_WAIT_RULE="queue/oldest-wait",SOURCE_EVENT_KINDS=["source-poll","source-declaration"],SOURCE_POLL_STATES=["current","unreachable","refused","malformed","not-running"],SOURCE_STATES=[...SOURCE_POLL_STATES,"stale","never-polled"],SOURCE_DEFAULT_INTERVAL_SEC=10,SOURCE_MIN_INTERVAL_SEC=2,QUEUE_DEFAULT_OLDEST_WAIT_MIN=10,SOURCE_MAX_GROUPS=500,SOURCE_MAX_BYTES=256*1024,SOURCE_STALE_PERIODS=3,SOURCE_STALE_MIN_MS=3e4;export function sourceStaleAfterMs(r){return Math.max(SOURCE_STALE_MIN_MS,SOURCE_STALE_PERIODS*Math.max(0,r))}n(sourceStaleAfterMs,"sourceStaleAfterMs"),e(sourceStaleAfterMs,"sourceStaleAfterMs");const o=e(r=>typeof r=="object"&&r!==null&&!Array.isArray(r),"isObj"),i=e(r=>typeof r=="number"&&Number.isInteger(r)&&r>=0,"isCount"),c=e(r=>typeof r=="number"&&Number.isFinite(r)&&r>0,"isTime"),a=e((r,t)=>typeof r=="string"&&r.length>0&&r.length<=t,"isStr");function l(r){if(!SOURCE_KINDS_READ.includes(r.sourceKind)||!a(r.name,200)||typeof r.path!="string"||typeof r.intervalSec!="number")return!1;const t=r.thresholds;return o(t)&&typeof t.oldestWaitMin=="number"&&t.oldestWaitMin>0}n(l,"f"),e(l,"asDecl");function p(r){if(!o(r)||!a(r.group,1e3)||!i(r.pending))return!1;for(const u of["inFlight","failed","completedInWindow"])if(r[u]!==void 0&&!i(r[u]))return!1;const t=r.oldestPendingAt;if(t!=null&&typeof t!="string")return!1;const s=r.labels;return s===void 0||o(s)&&Object.values(s).every(u=>typeof u=="string")}n(p,"l"),e(p,"asGroup");function S(r){if(!o(r)||typeof r.at!="string"||!c(r.receivedAt)||!Array.isArray(r.groups))return!1;const t=r.totals;if(!o(t)||!i(t.groups)||!i(t.pending)||!i(t.inFlight)||!i(t.failed))return!1;const s=r.truncated;return s!==void 0&&!(o(s)&&i(s.groups))?!1:r.groups.length<=SOURCE_MAX_GROUPS&&r.groups.every(p)}n(S,"d"),e(S,"asSnapshot");export function asSourcePollRaw(r){if(!(!o(r)||r.kind!=="source-poll"||!a(r.project,200)||!l(r))&&SOURCE_POLL_STATES.includes(r.state)&&!(!c(r.polledAt)||!c(r.reportEveryMs))&&!(r.snapshot!==void 0&&!S(r.snapshot))&&!(r.state==="current"&&r.snapshot===void 0))return r}n(asSourcePollRaw,"asSourcePollRaw"),e(asSourcePollRaw,"asSourcePollRaw");export function asSourceDeclarationRaw(r){if(!(!o(r)||r.kind!=="source-declaration"||!a(r.project,200))&&!(!Array.isArray(r.sources)||!r.sources.every(t=>o(t)&&l(t)))&&!(!Array.isArray(r.problems)||!r.problems.every(t=>typeof t=="string")))return r}n(asSourceDeclarationRaw,"asSourceDeclarationRaw"),e(asSourceDeclarationRaw,"asSourceDeclarationRaw");

package/package.json

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