@lensmcp/protocol-types 1.16.31 → 1.17.0

package/index.d.ts

@@ -7,4 +7,5 @@ export * from './lib/edge.js';
 export * from './lib/attributes.js';
 export * from './lib/resources.js';
 export * from './lib/tokens.js';
+export * from './lib/capture-demand.js';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC"}

package/index.js

@@ -7,3 +7,4 @@ export * from './lib/edge.js';
 export * from './lib/attributes.js';
 export * from './lib/resources.js';
 export * from './lib/tokens.js';
+export * from './lib/capture-demand.js';

package/lib/capture-demand.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Visual-capture DEMAND contract — the cross-process rendezvous between the
+ * MCP server (which asks for a frame) and the browser-capture runner (which
+ * owns Chrome).
+ *
+ * Why a file and not the event bus: the bus is ONE-WAY. Producers (the Vite
+ * plugin, the NestJS instrumentation, the capture runner) append to
+ * `LENSMCP_EVENT_FILE` / the UDS socket and the MCP session tails it — nothing
+ * flows back. So `visual.capture_frame` publishing a `visual-capture-request`
+ * onto the MCP's in-process bus was a DEAD LETTER: the runner never saw it,
+ * which is why capture had to poll a live Chrome forever (measured on a real
+ * machine, 2026-07-29: 2 runners + >1GB of Chrome resident for 1d8h with
+ * nobody capturing). Both processes already share the event-file directory, so
+ * a single-line request file there is the cheapest signal that actually
+ * crosses the boundary — the runner stats one small file instead of holding a
+ * browser open on the chance someone asks.
+ *
+ * This module is deliberately node-free (no `node:path`/`node:fs`): protocol
+ * types are bundled into the BROWSER client runtime, so it exports only the
+ * filename + payload shape. Each side does its own path join / IO.
+ */
+import type { VisualFrameCause } from './attributes.js';
+/** Request-file name, resolved as a sibling of `LENSMCP_EVENT_FILE`. */
+export declare const CAPTURE_REQUEST_FILENAME = "capture-request.json";
+/**
+ * Presence-file name (same directory). The runner writes it at startup and
+ * removes it on a clean stop.
+ *
+ * Its job is to keep the requester honest: `visual.capture_frame` now WAITS for
+ * the fresh frame it asked for (a cold browser needs ~1s), and without a way to
+ * tell "a runner is warming up" from "no runner exists" that wait would also be
+ * paid by every workspace running with capture disabled or no Chrome installed
+ * — an 8s stall for a frame that is never coming. With this, the tool waits
+ * only when a live runner is actually listening, and can say so when it isn't.
+ */
+export declare const CAPTURE_PRESENCE_FILENAME = "capture-runner.json";
+/** Advertised by a live capture runner. `pid` is checkable with `kill(pid, 0)`,
+ *  so a runner that was SIGKILLed leaves a file that readers can tell is dead. */
+export interface CapturePresence {
+    pid: number;
+    /** `Date.now()` at runner startup. */
+    startedAt: number;
+    /** Dev URL this runner captures. */
+    url: string;
+}
+/** One capture request. Written whole (single `writeFileSync`) so a reader
+ *  never sees a half-written line; `requestedAt` is the demand clock the
+ *  runner's idle timer works off. */
+export interface CaptureRequest {
+    /** `Date.now()` when the request was made. */
+    requestedAt: number;
+    /** Why the frame was asked for — becomes the frame's `causedBy`. Validate on
+     *  read (`VisualFrameCauseSchema`): this arrives from another process, and a
+     *  hand-edited file must not put a bogus cause on a published frame. */
+    cause: VisualFrameCause;
+    /** Whether to treat the captured frame as the stable final state. */
+    stable: boolean;
+    /** Opaque id, so a reader can tell two same-millisecond requests apart. */
+    requestId?: string;
+}
+//# sourceMappingURL=capture-demand.d.ts.map

package/lib/capture-demand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-demand.d.ts","sourceRoot":"","sources":["../../src/lib/capture-demand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D;kFACkF;AAClF,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;qCAEqC;AACrC,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB;;4EAEwE;IACxE,KAAK,EAAE,gBAAgB,CAAC;IACxB,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/lib/capture-demand.js

@@ -0,0 +1,14 @@
+/** Request-file name, resolved as a sibling of `LENSMCP_EVENT_FILE`. */
+export const CAPTURE_REQUEST_FILENAME = 'capture-request.json';
+/**
+ * Presence-file name (same directory). The runner writes it at startup and
+ * removes it on a clean stop.
+ *
+ * Its job is to keep the requester honest: `visual.capture_frame` now WAITS for
+ * the fresh frame it asked for (a cold browser needs ~1s), and without a way to
+ * tell "a runner is warming up" from "no runner exists" that wait would also be
+ * paid by every workspace running with capture disabled or no Chrome installed
+ * — an 8s stall for a frame that is never coming. With this, the tool waits
+ * only when a live runner is actually listening, and can say so when it isn't.
+ */
+export const CAPTURE_PRESENCE_FILENAME = 'capture-runner.json';

package/lib/resources.d.ts

@@ -13,9 +13,9 @@ export declare const ResourceEnvelopeSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ResourceEnvelope = z.infer<typeof ResourceEnvelopeSchema>;
 export declare const AgentStatusKindSchema: z.ZodEnum<{
-    warning: "warning";
     starting: "starting";
     clean: "clean";
+    warning: "warning";
     failing: "failing";
 }>;
 export type AgentStatusKind = z.infer<typeof AgentStatusKindSchema>;
@@ -23,9 +23,9 @@ export declare const AgentBlockingItemSchema: z.ZodObject<{
     source: z.ZodString;
     severity: z.ZodEnum<{
         error: "error";
+        warning: "warning";
         debug: "debug";
         info: "info";
-        warning: "warning";
         fatal: "fatal";
     }>;
     title: z.ZodString;
@@ -45,37 +45,37 @@ export declare const AgentBlockingItemSchema: z.ZodObject<{
 export type AgentBlockingItem = z.infer<typeof AgentBlockingItemSchema>;
 export declare const AgentChecksSchema: z.ZodObject<{
     typecheck: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     lint: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     build: z.ZodOptional<z.ZodEnum<{
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     visual: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
     memory: z.ZodOptional<z.ZodEnum<{
         warning: "warning";
-        unknown: "unknown";
         passed: "passed";
         failed: "failed";
+        unknown: "unknown";
     }>>;
 }, z.core.$strip>;
 export declare const AgentCurrentStatusSchema: z.ZodObject<{
@@ -85,9 +85,9 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
     updatedAt: z.ZodOptional<z.ZodString>;
     sessionId: z.ZodString;
     status: z.ZodEnum<{
-        warning: "warning";
         starting: "starting";
         clean: "clean";
+        warning: "warning";
         failing: "failing";
     }>;
     activeTab: z.ZodOptional<z.ZodString>;
@@ -96,9 +96,9 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
         source: z.ZodString;
         severity: z.ZodEnum<{
             error: "error";
+            warning: "warning";
             debug: "debug";
             info: "info";
-            warning: "warning";
             fatal: "fatal";
         }>;
         title: z.ZodString;
@@ -119,9 +119,9 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
         source: z.ZodString;
         severity: z.ZodEnum<{
             error: "error";
+            warning: "warning";
             debug: "debug";
             info: "info";
-            warning: "warning";
             fatal: "fatal";
         }>;
         title: z.ZodString;
@@ -141,41 +141,71 @@ export declare const AgentCurrentStatusSchema: z.ZodObject<{
     suggestedReads: z.ZodArray<z.ZodString>;
     checks: z.ZodOptional<z.ZodObject<{
         typecheck: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         lint: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         build: z.ZodOptional<z.ZodEnum<{
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         visual: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
         memory: z.ZodOptional<z.ZodEnum<{
             warning: "warning";
-            unknown: "unknown";
             passed: "passed";
             failed: "failed";
+            unknown: "unknown";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AgentCurrentStatus = z.infer<typeof AgentCurrentStatusSchema>;
+/**
+ * Hot-tier retention pressure.
+ *
+ * WHY it is on the bootstrap surface: every retention cap used to be a COUNT
+ * cap over payloads of arbitrary size, so the hot tier could hold hundreds of
+ * MB while every counter still read "5 000 events" — the growth was
+ * invisible from the outside (the MCP server was found at 395–720 MB RSS by
+ * looking at the process, not at any lens surface). These are the numbers
+ * that make a bounded tier observable: what is resident in BYTES, what was
+ * evicted to stay inside the budget, and how many producer payloads the
+ * ingest clamp had to shrink. `truncatedEvents` climbing is the signal that
+ * some producer is attaching megabytes per event.
+ */
+export declare const AgentStorageStatsSchema: z.ZodObject<{
+    eventsResident: z.ZodNumber;
+    eventsResidentBytes: z.ZodNumber;
+    eventsIngested: z.ZodNumber;
+    eventsDropped: z.ZodNumber;
+    eventsDroppedForBytes: z.ZodOptional<z.ZodNumber>;
+    eventCap: z.ZodOptional<z.ZodNumber>;
+    eventByteCap: z.ZodOptional<z.ZodNumber>;
+    artifactsResident: z.ZodOptional<z.ZodNumber>;
+    artifactsResidentBytes: z.ZodOptional<z.ZodNumber>;
+    artifactsDropped: z.ZodOptional<z.ZodNumber>;
+    artifactByteCap: z.ZodOptional<z.ZodNumber>;
+    truncatedEvents: z.ZodOptional<z.ZodNumber>;
+    truncatedBytesReclaimed: z.ZodOptional<z.ZodNumber>;
+    rawByteLimit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AgentStorageStats = z.infer<typeof AgentStorageStatsSchema>;
 export declare const AgentSessionSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodLiteral<1>;
@@ -200,6 +230,22 @@ export declare const AgentSessionSchema: z.ZodObject<{
         name: z.ZodString;
         nxVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+    storage: z.ZodOptional<z.ZodObject<{
+        eventsResident: z.ZodNumber;
+        eventsResidentBytes: z.ZodNumber;
+        eventsIngested: z.ZodNumber;
+        eventsDropped: z.ZodNumber;
+        eventsDroppedForBytes: z.ZodOptional<z.ZodNumber>;
+        eventCap: z.ZodOptional<z.ZodNumber>;
+        eventByteCap: z.ZodOptional<z.ZodNumber>;
+        artifactsResident: z.ZodOptional<z.ZodNumber>;
+        artifactsResidentBytes: z.ZodOptional<z.ZodNumber>;
+        artifactsDropped: z.ZodOptional<z.ZodNumber>;
+        artifactByteCap: z.ZodOptional<z.ZodNumber>;
+        truncatedEvents: z.ZodOptional<z.ZodNumber>;
+        truncatedBytesReclaimed: z.ZodOptional<z.ZodNumber>;
+        rawByteLimit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AgentSession = z.infer<typeof AgentSessionSchema>;
 //# sourceMappingURL=resources.d.ts.map

package/lib/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/lib/resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;GAGG;AACH,eAAO,MAAM,WAAW,+OAyBd,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrD,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO5B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAI1E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAgB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/lib/resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;GAGG;AACH,eAAO,MAAM,WAAW,+OAyBd,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrD,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO5B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAI1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAmBlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/lib/resources.js

@@ -75,6 +75,39 @@ export const AgentCurrentStatusSchema = ResourceEnvelopeSchema.extend({
     checks: AgentChecksSchema.optional(),
 });
 // -------- agent://session --------
+/**
+ * Hot-tier retention pressure.
+ *
+ * WHY it is on the bootstrap surface: every retention cap used to be a COUNT
+ * cap over payloads of arbitrary size, so the hot tier could hold hundreds of
+ * MB while every counter still read "5 000 events" — the growth was
+ * invisible from the outside (the MCP server was found at 395–720 MB RSS by
+ * looking at the process, not at any lens surface). These are the numbers
+ * that make a bounded tier observable: what is resident in BYTES, what was
+ * evicted to stay inside the budget, and how many producer payloads the
+ * ingest clamp had to shrink. `truncatedEvents` climbing is the signal that
+ * some producer is attaching megabytes per event.
+ */
+export const AgentStorageStatsSchema = z.object({
+    eventsResident: z.number().int().nonnegative(),
+    eventsResidentBytes: z.number().int().nonnegative(),
+    eventsIngested: z.number().int().nonnegative(),
+    eventsDropped: z.number().int().nonnegative(),
+    /** Of `eventsDropped`, those evicted because the BYTE budget was hit. */
+    eventsDroppedForBytes: z.number().int().nonnegative().optional(),
+    eventCap: z.number().int().nonnegative().optional(),
+    eventByteCap: z.number().int().nonnegative().optional(),
+    artifactsResident: z.number().int().nonnegative().optional(),
+    artifactsResidentBytes: z.number().int().nonnegative().optional(),
+    artifactsDropped: z.number().int().nonnegative().optional(),
+    artifactByteCap: z.number().int().nonnegative().optional(),
+    /** Events whose `raw` exceeded the per-event limit and was shrunk. */
+    truncatedEvents: z.number().int().nonnegative().optional(),
+    /** Approximate bytes never admitted thanks to that truncation. */
+    truncatedBytesReclaimed: z.number().int().nonnegative().optional(),
+    /** The per-event `raw` limit in force. */
+    rawByteLimit: z.number().int().nonnegative().optional(),
+});
 export const AgentSessionSchema = ResourceEnvelopeSchema.extend({
     sessionId: z.string(),
     supportedResources: z.array(z.string()),
@@ -91,4 +124,6 @@ export const AgentSessionSchema = ResourceEnvelopeSchema.extend({
         name: z.string(),
         nxVersion: z.string().optional(),
     }),
+    /** Optional — absent when the backend reports no stats. */
+    storage: AgentStorageStatsSchema.optional(),
 });

package/package.json

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