glasspane-mcp 1.1.1 → 1.1.2

package/dist/dispatch.d.ts

@@ -26,7 +26,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
 export declare const SERVER_INFO: {
     readonly name: "glasspane-mcp";
-    readonly version: "1.1.1";
+    readonly version: "1.1.2";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/engine-client.d.ts

@@ -12,10 +12,36 @@ export declare function daemonUnreachableRemedy(): string;
 /** Env override for the daemon socket path (default below). */
 export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
 /**
- * The daemon listens here by default (spec §3.1). Single source: the CLI
- * argument parser in index.ts and the reconnecting transport both resolve the
- * path through this function, so an env override cannot be honoured on one side
- * only.
+ * Where this shell connects when nothing was named, in order: `GLASSPANE_ENGINE_SOCK`
+ * (the env var {@link ENGINE_SOCKET_ENV} spells), then the explicit
+ * `--socket-path` this shell's own CLI accepts, then the fallback below.
+ *
+ * The fallback is a **guess made from `$HOME`**, and it is worth being exact
+ * about which guess: `os.homedir()` reads `$HOME`, while the daemon's own
+ * default is `StateRoot.homeDefault()` = `NSHomeDirectory() + "/.glasspane"`,
+ * which on macOS does **not** consult `$HOME` — the same non-inheritance that
+ * has already cost this project real data, and the reason a caller cannot
+ * isolate a run by exporting `HOME`. So in a process whose `$HOME` points into
+ * a sandbox the two sides resolve **different directories**: this shell goes
+ * looking for `$HOME/.glasspane/engine.sock` inside the sandbox while the daemon
+ * is still serving only the socket under the real home. Nor is there a third
+ * case to cover by guessing better — a daemon started with `--state-dir <root>`
+ * listens on `<root>/daemon.sock`, which no value of `$HOME` points at.
+ *
+ * The reliable route is therefore to stop deriving and to say which socket: set
+ * `GLASSPANE_ENGINE_SOCK`, or pass `--socket-path`. The installer's launchd job
+ * hands the daemon an explicit `--socket-path` already, which is what makes an
+ * installed pair agree — so read that value back rather than recomputing it;
+ * this shell's `--help` gives the command.
+ *
+ * Deliberately not "fixed" by asking the daemon: before a connection exists
+ * there is no daemon to ask, and `hello` is itself answered after connecting.
+ * Matching the daemon's home lookup from Node would take an FFI call to
+ * `NSHomeDirectory()`, which this shell does not have.
+ *
+ * Single source all the same: the CLI argument parser in index.ts and the
+ * reconnecting transport both resolve the path through this function, so an env
+ * override cannot be honoured on one side only.
  */
 export declare function defaultSocketPath(): string;
 /** Fallback deadline for a method missing from the table below. */

package/dist/index.js

@@ -1075,9 +1075,11 @@ function evidenceSummaryLines(pack) {
   }
   const act = pack.signals.act;
   lines.push(`act ${act.action} ${selectorText(act.selector)}: ${act.actConfirmed ? "confirmed" : "rejected"}`);
-  if (pack.signals.axEvent !== void 0) {
+  if (pack.signals.axEvent !== void 0 && pack.signals.axEvent !== null) {
     const ax = pack.signals.axEvent;
     lines.push(`axEvent: changed=${ax.axChanged} nodes=${ax.nodeCount} latencyMs=${doubleText(ax.latencyMs)}`);
+  } else {
+    lines.push(AX_EVENT_NOT_MEASURED);
   }
   lines.push(
     pack.signals.handlerProbe !== void 0 && pack.signals.handlerProbe !== null ? handlerProbeText(pack.signals.handlerProbe) : HANDLER_PROBE_NOT_MEASURED
@@ -1085,7 +1087,7 @@ function evidenceSummaryLines(pack) {
   lines.push(
     pack.signals.stateDiff !== void 0 && pack.signals.stateDiff !== null ? stateDiffText(pack.signals.stateDiff) : STATE_DIFF_NOT_MEASURED
   );
-  if (pack.signals.pixelDiff !== void 0) {
+  if (pack.signals.pixelDiff !== void 0 && pack.signals.pixelDiff !== null) {
     const px = pack.signals.pixelDiff;
     let line = `pixelDiff: changedRatio=${doubleText(px.changedPixelRatio)} windowId=${px.windowId}`;
     if (px.bounds !== null) {
@@ -1093,14 +1095,20 @@ function evidenceSummaryLines(pack) {
       line += ` bounds=${doubleText(b.x)},${doubleText(b.y)},${doubleText(b.width)},${doubleText(b.height)}`;
     }
     lines.push(line);
+  } else {
+    lines.push(PIXEL_DIFF_NOT_MEASURED);
   }
-  if (pack.signals.responsiveness !== void 0) {
+  if (pack.signals.responsiveness !== void 0 && pack.signals.responsiveness !== null) {
     const r = pack.signals.responsiveness;
     lines.push(`responsiveness: responsive=${r.responsive} pingMs=${doubleText(r.pingMs)}`);
+  } else {
+    lines.push(RESPONSIVENESS_NOT_MEASURED);
   }
-  if (pack.signals.crash !== void 0) {
+  if (pack.signals.crash !== void 0 && pack.signals.crash !== null) {
     const c = pack.signals.crash;
     lines.push(`crash: aliveBefore=${c.processAliveBefore} aliveAfter=${c.processAliveAfter}`);
+  } else {
+    lines.push(CRASH_NOT_MEASURED);
   }
   return lines;
 }
@@ -1154,6 +1162,10 @@ function escapeHTML(value) {
 var NO_DIAGNOSIS_TEXT = "\u2014 (no diagnosis recorded: this pack carries none; run gp_diagnose for this operationId, then gp_export_evidence again)";
 var HANDLER_PROBE_NOT_MEASURED = "handlerProbe: not measured (no probe connection served this act window)";
 var STATE_DIFF_NOT_MEASURED = "stateDiff: not measured (the probe reported no state channel)";
+var AX_EVENT_NOT_MEASURED = "axEvent: not measured (this pack carries no AX tree digest)";
+var PIXEL_DIFF_NOT_MEASURED = "pixelDiff: not measured (this pack carries no pixel comparison)";
+var RESPONSIVENESS_NOT_MEASURED = "responsiveness: not measured (this pack carries no responsiveness round trip)";
+var CRASH_NOT_MEASURED = "crash: not measured (this pack carries no process liveness sample)";
 var MAX_HANDLERS_SHOWN = 8;
 var MAX_ENTRIES_SHOWN = 8;
 function sections(pack, diagnostics) {
@@ -1736,6 +1748,15 @@ var ObserveArgs = z5.strictObject({
   maxDepth: OptionalDepthSchema,
   role: OptionalRoleSchema
 });
+var OptionalHitTargetSchema = z5.number().min(1).max(400).optional();
+var OptionalScaleSchema = z5.number().min(0.1).max(1).optional();
+var CaptureViewArgs = z5.strictObject({
+  scale: OptionalScaleSchema
+});
+var AuditUiArgs = z5.strictObject({
+  maxDepth: OptionalDepthSchema,
+  minHitTargetPt: OptionalHitTargetSchema
+});
 var ActArgs = z5.strictObject({
   selector: SelectorSchema,
   action: ActionSchema,
@@ -1828,7 +1849,7 @@ var TOOL_SPECS = [
   },
   {
     name: "gp_act",
-    description: "Perform a UI action on the attached app and confirm it. If the daemon reports GP_E_BUSY_INPUT (real user input is contaminating the window), retry later, or set degrade: true to proceed immediately with the contamination recorded in evidence (attribution becomes weak + contaminated=true) \u2014 never silently clean.",
+    description: "Perform a UI action on the attached app and confirm it. If the daemon reports GP_E_BUSY_INPUT (real user input is contaminating the window), retry later, or set degrade: true to proceed immediately with the contamination recorded in evidence (attribution becomes weak + contaminated=true) \u2014 never silently clean. Prefer selector.identifier over selector.title to name the element: a title is not a stable handle (a measured case: every act against a title-keyed selector reported actConfirmed while the app's handler never ran, because the press resolved to something that was not the button). actConfirmed means the accessibility action was accepted \u2014 not that the intended element handled it; to prove the click itself, read the probe's handler hit or the state change, or assert_element against a value that the action is supposed to change.",
     engineMethod: "act",
     inputSchema: {
       type: "object",
@@ -1861,6 +1882,34 @@ var TOOL_SPECS = [
     },
     validate: zodBridge(AssertElementArgs)
   },
+  {
+    name: "gp_audit_ui",
+    description: "Audit the attached app's layout for operability: element geometry plus deterministic rules report zero-sized or out-of-window controls (blocking), undersized hit targets, clipped elements and frame overlaps (advisory). The verdict distinguishes pass from insufficient: unmeasured geometry never counts as a clean result. Read-only \u2014 it records no operation.",
+    engineMethod: "audit_ui",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        maxDepth: { type: "integer", minimum: 1, maximum: 10 },
+        minHitTargetPt: { type: "number", minimum: 1, maximum: 400 }
+      }
+    },
+    validate: zodBridge(AuditUiArgs)
+  },
+  {
+    name: "gp_capture_view",
+    description: "Send the attached app's current window to your model once, as a PNG, for visual review. This is the only tool that moves image pixels, and it is a pass-through: the engine encodes the capture and writes nothing to disk (the result says persisted: false). Use it for what measurements cannot judge \u2014 visual taste, layout that reads as wrong, content with no accessibility tree. For anything assertable, prefer gp_audit_ui / gp_assert_element: a measurement repeats, a visual impression does not. `scale` is a pixel-density factor applied to the captured image (window size is reported separately in points as pointSize), and the summary states both the requested scale and the appliedScale actually present in the image. WARNING: the image enters this conversation, so anything your model provider logs will retain whatever was on screen. Needs the daemon's Screen Recording grant; oversized windows are refused with a suggested scale rather than silently downsampled.",
+    engineMethod: "capture_view",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        scale: { type: "number", minimum: 0.1, maximum: 1 }
+      }
+    },
+    validate: zodBridge(CaptureViewArgs),
+    execute: captureView
+  },
   {
     name: "gp_diagnose",
     description: "Diagnose the most recent (or the given) operation.",
@@ -1934,7 +1983,7 @@ var TOOL_SPECS = [
   },
   {
     name: "gp_probe_status",
-    description: "List GlassPaneProbe connections and whether the attached app has a live probe \u2014 probe presence is what makes T4/T5/T7/T8 verdicts and tier-1 checkpoint restores decidable. `probes` holds **live** registrations only (every row `connected: true`), so a probe that dropped is absent from it rather than flagged inside it: read `recentDisconnections` for that history (`pid`, `disconnectReason`, `disconnectedAt`, per-pid `drops`), and `disconnections` is just the total count since start. Each live row can also carry the frame-accounting that makes a zero verdict readable: `stateFramesUnmappedSource` (daemon-side, per pid), and `droppedEvents` / `droppedWrites` / `rejectedKeys` as the probe itself reported them \u2014 those are **absent when unreported**, which is not the same as zero, and `unmapableStateFrames` is the daemon-side total that survives a disconnect.",
+    description: "List GlassPaneProbe connections and whether the attached app has a live probe \u2014 probe presence is what makes T4/T5/T7/T8 verdicts and tier-1 checkpoint restores decidable. `attachedHasProbe` is that yes/no for the attached app; `probes` holds **live** registrations only (every row `connected: true`), so a probe that dropped is absent from it rather than flagged inside it: read `recentDisconnections` for that history (`pid`, `disconnectReason`, `disconnectedAt`, per-pid `drops`), and `disconnections` is just the total count since start. Each live row can also carry the frame-accounting that makes a zero verdict readable: `stateFramesUnmappedSource` (daemon-side, per pid), and `droppedEvents` / `droppedWrites` / `rejectedKeys` as the probe itself reported them \u2014 those are **absent when unreported**, which is not the same as zero, and `unmapableStateFrames` is the daemon-side total that survives a disconnect. The same reply is where the T9 degradation watch is readable without performing an action, under `degradation` (absent when this daemon runs without T9 wired): `tier` is `healthy` / `watch` / `degrading`, and `judged` says whether that tier is a measurement at all \u2014 `judged: false` with `tier: healthy` means the window was too thin or too short to read, **not** that the app is clean; `basis` spells out which of those it is with the numbers, alongside `samples`/`minimumSamples` and `spanSeconds`/`minimumSpanSeconds`. `longSession` marks the window spanning at least the long-session threshold; it is context for the trend, and it never changes `tier` by itself. `drivers` appears only when something is trending, and `slopes` carries only the channels that produced one (`pingMsPerSec`, `memoryBytesPerSec`, `handlesPerSec`) \u2014 a channel missing from `slopes` was never read, which is not a rate of zero.",
     engineMethod: "probe_status",
     inputSchema: {
       type: "object",
@@ -2161,6 +2210,69 @@ function packForReport(pack, measuredSchemaVersion) {
   }
   return { ...pack, schemaVersion: `${measuredSchemaVersion} (read as ${pack.schemaVersion})` };
 }
+async function captureView(args, context) {
+  try {
+    const raw = await context.engine.call("capture_view", args);
+    const body = raw ?? {};
+    const png = body.pngBase64;
+    if (typeof png !== "string" || png.length === 0) {
+      return {
+        content: [{ type: "text", text: formatToolError(
+          GP_E_INTERNAL,
+          "capture_view answered without a pngBase64 payload",
+          "retry once; if it repeats, report this \u2014 the engine captured but the shell could not read the image"
+        ) }],
+        isError: true
+      };
+    }
+    if (body.persisted !== false) {
+      return {
+        content: [{ type: "text", text: formatToolError(
+          GP_E_INTERNAL,
+          `capture_view answered without persisted:false (got ${JSON.stringify(body.persisted ?? null)})`,
+          "do not treat this image as unsaved: the engine did not say so. Retry once, then report the frame shape \u2014 the pass-through guarantee is a claim about the protocol, not a default the shell may fill in"
+        ) }],
+        isError: true
+      };
+    }
+    const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
+    const summary = canonicalJson({
+      mimeType,
+      byteCount: body.byteCount,
+      pixelWidth: body.pixelWidth,
+      pixelHeight: body.pixelHeight,
+      scale: body.scale,
+      // 实际应用的倍率与请求值都给出：静默降采样失败时，"appliedScale" 才是
+      // 模型该信的那个数（它决定自己看到的是不是缩过的版本）。
+      appliedScale: body.appliedScale,
+      windowId: body.windowId,
+      pointSize: body.pointSize,
+      persisted: body.persisted
+    });
+    return {
+      content: [
+        { type: "image", data: png, mimeType },
+        { type: "text", text: summary }
+      ],
+      isError: false
+    };
+  } catch (error) {
+    if (error instanceof EngineCallError) {
+      return {
+        content: [{ type: "text", text: formatToolErrorShape(error.toBody()) }],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: formatToolError(
+        GP_E_INTERNAL,
+        `internal shell error: ${String(error)}`,
+        "see the MCP server logs and retry"
+      ) }],
+      isError: true
+    };
+  }
+}
 function mapEvidenceReadError(error) {
   if (error instanceof EvidenceFrameShapeError) {
     return {
@@ -2350,7 +2462,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.1.1" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.1.2" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -2499,8 +2611,23 @@ function parseArgs(argv) {
 var USAGE = `usage: glasspane-mcp [--socket-path <path>]
 
 Bridges an AI agent (MCP stdio) to the GlassPane engine daemon.
-The daemon socket defaults to $HOME/.glasspane/engine.sock
-(override with GLASSPANE_ENGINE_SOCK or --socket-path).
+
+Socket, in the order this shell resolves it:
+  1. --socket-path <path>
+  2. GLASSPANE_ENGINE_SOCK=<path>
+  3. $HOME/.glasspane/engine.sock \u2014 a guess read from this process's HOME, not
+     the daemon's rule: glasspaned's own default is the home folder the system
+     reports, which a HOME you export does not move, and glasspaned --state-dir
+     <dir> serves <dir>/daemon.sock instead.
+
+So "nothing is listening on the default path" means this shell guessed a
+different directory, not that the daemon is dead. Connect to the socket the
+daemon is really on \u2014 read it, do not re-derive it:
+  launchctl print gui/$(id -u)/com.glasspane.daemon      # the installed job's --socket-path value
+  glasspane-mcp --socket-path <that path>                 # or, equivalently:
+  GLASSPANE_ENGINE_SOCK=<that path> glasspane-mcp
+A daemon started by hand with --state-dir has no launchd job to read: pass it
+<state-dir>/daemon.sock.
 `;
 var DRAIN_WAIT_MS = 3e4;
 function logNote(text) {

package/dist/tools.d.ts

@@ -44,6 +44,25 @@ export declare const ObserveArgs: z.ZodObject<{
     maxDepth?: number | undefined;
 }>;
 export type ObserveArgs = z.infer<typeof ObserveArgs>;
+export declare const CaptureViewArgs: z.ZodObject<{
+    scale: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    scale?: number | undefined;
+}, {
+    scale?: number | undefined;
+}>;
+export type CaptureViewArgs = z.infer<typeof CaptureViewArgs>;
+export declare const AuditUiArgs: z.ZodObject<{
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+    minHitTargetPt: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxDepth?: number | undefined;
+    minHitTargetPt?: number | undefined;
+}, {
+    maxDepth?: number | undefined;
+    minHitTargetPt?: number | undefined;
+}>;
+export type AuditUiArgs = z.infer<typeof AuditUiArgs>;
 export declare const ActArgs: z.ZodObject<{
     selector: z.ZodObject<{
         role: z.ZodString;
@@ -248,12 +267,23 @@ export interface ToolExecuteContext {
      */
     turn: TrailTurn;
 }
+/**
+ * Content parts a tool may return. `image` exists for exactly one tool:
+ * `gp_capture_view`, whose whole point is handing one window image to the
+ * user's own model. It is a pass-through, not a store — the shell writes
+ * nothing to disk, so "no raw screenshot is persisted anywhere" stays true.
+ */
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
 /** Tool result shape shared by the default path and custom executors. */
 export interface ToolResult {
-    content: Array<{
-        type: "text";
-        text: string;
-    }>;
+    content: ToolContent[];
     isError: boolean;
 }
 export declare const TOOL_SPECS: readonly ToolSpec[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glasspane-mcp",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "GlassPane MCP stdio shell: JSON-RPC 2.0 over stdio bridging an AI agent to the glasspane engine daemon",
   "type": "module",
   "main": "./dist/index.js",