glasspane-mcp 1.24.1 → 1.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,8 +12,11 @@ package alone does not give you a working verification engine.
12
12
 
13
13
  ```bash
14
14
  # Fetch install.sh, then run it — two steps on purpose: piped into `sh`, a curl that fails
15
- # leaves stdin empty and the pipeline exits 0 while nothing was installed.
16
- curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh -o /tmp/gp-install.sh && sh /tmp/gp-install.sh
15
+ # leaves stdin empty and the pipeline exits 0 while nothing was installed. The landing file
16
+ # comes from `mktemp`: `/tmp` is mode 1777 and the sticky bit does not stop another account
17
+ # from creating `/tmp/gp-install.sh -> ~/.bashrc` first — `curl -o` follows that symlink and
18
+ # truncates the target as *you*.
19
+ GP="$(mktemp "${TMPDIR:-/tmp/}gp-install.XXXXXXXX")" && curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh -o "$GP" && sh "$GP" && rm -f "$GP"
17
20
  # 或:npx glasspane-install
18
21
  ```
19
22
 
@@ -26,7 +26,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
26
26
  export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
27
27
  export declare const SERVER_INFO: {
28
28
  readonly name: "glasspane-mcp";
29
- readonly version: "1.24.1";
29
+ readonly version: "1.26.0";
30
30
  };
31
31
  export declare const PARSE_ERROR = -32700;
32
32
  export declare const INVALID_REQUEST = -32600;
@@ -342,8 +342,6 @@ export declare function writeBacklogRemedy(backlogBytes: number, limitBytes: num
342
342
  * effect.
343
343
  */
344
344
  export declare function slowEngineRemedy(method: string, surface?: ShellSurface): string;
345
- /** Log ceiling for a frame body; excess is marked, never silently cut. */
346
- export declare const LOG_BODY_CHARS: number;
347
345
  /**
348
346
  * How a reply frame was matched to the request it is reported for.
349
347
  *
@@ -589,7 +587,38 @@ export declare class EngineJsonRpcClient {
589
587
  private handshake;
590
588
  private verifyIdentity;
591
589
  }
592
- export declare function truncate(text: string): string;
590
+ /**
591
+ * The one sentence every unattributable-frame arm says about the bytes it refused to log.
592
+ *
593
+ * `handleMessage` has seven arms that drop a frame the client cannot attribute — not JSON, not
594
+ * an object, an id it never issued, an id-less answer, a non-numeric id. Each of them still has
595
+ * to be diagnosable, and none of them may copy the frame: a reply on this socket is observe /
596
+ * assert content (element titles and values, sometimes a document's text), while the report
597
+ * sink — stderr, or whatever supervises the process — is a file this product never sets the
598
+ * mode of. Copying the body there exports screen content past the 0700 state root, which is
599
+ * exactly what `lateReplyBodyNote` was authored to prevent on the late-reply path; the two
600
+ * surfaces cannot be allowed to hold opposite rules about the same bytes (review 2026-10-09
601
+ * finding 3, F3 on 2026-10-27, and this round's finding that the seven arms were never moved).
602
+ *
603
+ * So the note keeps the facts that survive redaction and are recomputable from the frame
604
+ * itself: the byte length and a short deterministic SHA-256 digest of the exact bytes this
605
+ * transport received. Unlike a *reply* to a request this client still tracks, a frame that
606
+ * belongs to no request may have no archive entry at all, so the note names where content the
607
+ * daemon did record lives, and says how to read it back, without promising this frame is in it.
608
+ *
609
+ * The reverse mutation is to interpolate the frame back into any of those seven lines.
610
+ */
611
+ export declare function frameBodyNotLoggedNote(serializedFrame: string): string;
612
+ /**
613
+ * A single frame *field* quoted into a log line, bounded.
614
+ *
615
+ * A normal request id is a number or a short string, so it is printed exactly as it came —
616
+ * editing the daemon's words would be its own dishonesty. The bound is for the other case: a
617
+ * peer on this socket path that answers with an id-shaped field holding several kilobytes of
618
+ * text would otherwise put that text in the log through the one clause this file still trusted.
619
+ * Over the bound the value is reported by size and digest, the same shape as the frame note.
620
+ */
621
+ export declare function shortFieldValue(value: unknown): string;
593
622
  export declare function lateReplyBodyNote(serializedBody: string, operationId?: unknown): string;
594
623
  /** How a transport stream is opened; injectable so tests need no socket. */
595
624
  export type EngineTransportOpener = (socketPath: string) => Duplex;
@@ -150,8 +150,17 @@ var StreamLineIo = class {
150
150
  messageHandler = null;
151
151
  closeHandler = null;
152
152
  errorHandler = null;
153
- writeLine(line) {
154
- this.output.write(line + "\n");
153
+ writeLine(line, onHandedOff) {
154
+ const text = line + "\n";
155
+ if (onHandedOff === void 0) {
156
+ this.output.write(text);
157
+ return;
158
+ }
159
+ this.output.write(text, (error) => {
160
+ if (!error) {
161
+ onHandedOff();
162
+ }
163
+ });
155
164
  }
156
165
  bufferedBytes() {
157
166
  return this.output.writableLength;
@@ -423,7 +432,7 @@ function slowEngineRemedy(method, surface = "mcp") {
423
432
  return `${poll}. The daemon serves one request at a time and is still working on this one, so ${reIssueGuidance(surface)}; a restart is authorised only by ${restarted}`;
424
433
  }
425
434
  var LATE_REPLY_RETENTION = 16;
426
- var LOG_BODY_CHARS = 64 * 1024;
435
+ var LOG_FIELD_CHARS = 120;
427
436
  var EngineJsonRpcClient = class {
428
437
  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
429
438
  this.io = io;
@@ -577,7 +586,6 @@ var EngineJsonRpcClient = class {
577
586
  entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
578
587
  const backlog = this.io.bufferedBytes?.() ?? 0;
579
588
  if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
580
- this.pending.delete(id);
581
589
  this.reject(entry, new EngineCallError(
582
590
  GP_E_ENGINE_BACKLOG,
583
591
  `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
@@ -589,8 +597,12 @@ var EngineJsonRpcClient = class {
589
597
  const queuedBefore = this.io.bufferedBytes?.() ?? null;
590
598
  try {
591
599
  const frameText = JSON.stringify(frame);
592
- this.io.writeLine(frameText);
593
- if (queuedBefore !== null) {
600
+ let writeHandedOffConfirmed = false;
601
+ this.io.writeLine(frameText, () => {
602
+ writeHandedOffConfirmed = true;
603
+ entry.handedOff = true;
604
+ });
605
+ if (queuedBefore !== null && !writeHandedOffConfirmed) {
594
606
  const queuedAfter = this.io.bufferedBytes?.() ?? 0;
595
607
  entry.handedOff = queuedAfter < queuedBefore + frameText.length + 1;
596
608
  }
@@ -621,7 +633,8 @@ var EngineJsonRpcClient = class {
621
633
  this.report(
622
634
  `engine has not answered '${entry.method}' (id ${entry.id}) within ${entry.deadlineMs}ms \u2014 still in flight`
623
635
  );
624
- const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for an MCP client's sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
636
+ const waitingFor = this.surface === "mcp" ? "an MCP client" : "an HTTP caller";
637
+ const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for ${waitingFor}'s sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
625
638
  this.reject(entry, new EngineCallError(
626
639
  GP_E_ENGINE_TIMEOUT,
627
640
  `engine is still working on '${entry.method}': no reply after ${entry.deadlineMs}ms. The request stays registered \u2014 a late reply is written to the server log \u2014 so this is a busy or slow daemon, not an unreachable one. That registration lasts only while this connection does: if the transport ends first, the server log says so and names what it stopped tracking.` + capped,
@@ -650,11 +663,11 @@ var EngineJsonRpcClient = class {
650
663
  try {
651
664
  parsed = JSON.parse(line);
652
665
  } catch {
653
- this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
666
+ this.report(`engine sent a non-JSON frame, dropped: ${frameBodyNotLoggedNote(line)}`);
654
667
  return;
655
668
  }
656
669
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
657
- this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
670
+ this.report(`engine sent a frame that is not a JSON object, dropped: ${frameBodyNotLoggedNote(line)}`);
658
671
  return;
659
672
  }
660
673
  const frame = parsed;
@@ -665,7 +678,7 @@ var EngineJsonRpcClient = class {
665
678
  const tracked = [...this.pending.values()];
666
679
  const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
667
680
  this.report(
668
- `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
681
+ `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + frameBodyNotLoggedNote(line)
669
682
  );
670
683
  return;
671
684
  }
@@ -692,13 +705,13 @@ var EngineJsonRpcClient = class {
692
705
  this.retainForLateReply();
693
706
  return;
694
707
  }
695
- this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
708
+ this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${frameBodyNotLoggedNote(line)}`);
696
709
  return;
697
710
  }
698
- this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${truncate(line)}` : `engine sent an id-less frame with no request in flight: ${truncate(line)}`);
711
+ this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${frameBodyNotLoggedNote(line)}` : `engine sent an id-less frame with no request in flight: ${frameBodyNotLoggedNote(line)}`);
699
712
  return;
700
713
  }
701
- this.report(`engine sent a frame with a non-numeric request id (${jsonOrString(id)}), which this client never issues: ${truncate(line)}`);
714
+ this.report(`engine sent a frame with a non-numeric request id (${shortFieldValue(id)}), which this client never issues: ${frameBodyNotLoggedNote(line)}`);
702
715
  }
703
716
  settleFromFrame(entry, frame) {
704
717
  if (frame.error) {
@@ -735,12 +748,19 @@ var EngineJsonRpcClient = class {
735
748
  this.report(`the engine's late reply to '${entry.method}' (id ${entry.id}) exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes), so its body could not be delivered even late${inferred ? " (attributed by arrival order: the frame's head carried no readable id)" : ""}`);
736
749
  return;
737
750
  }
738
- this.pending.delete(entry.id);
739
- this.reject(entry, attribute(new EngineCallError(
751
+ const failure = new EngineCallError(
740
752
  GP_E_PAYLOAD_TOO_LARGE,
741
753
  `the engine's reply to '${entry.method}' exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes) and was dropped; the connection is intact and other requests are unaffected`,
742
754
  "narrow this request or ask for less of it; the tool's own schema names the parameters that can shrink a reply, and this shell rewrites this line into that advice when it can (the transport layer deliberately does not guess them)"
743
- ), entry, inferred));
755
+ );
756
+ if (inferred) {
757
+ this.reject(entry, attribute(failure, entry));
758
+ entry.arrivalOrderConsumed = true;
759
+ this.retainForLateReply();
760
+ return;
761
+ }
762
+ this.pending.delete(entry.id);
763
+ this.reject(entry, attribute(failure, entry, false));
744
764
  }
745
765
  /**
746
766
  * The daemon's error frame, mapped into this shell's error.
@@ -955,8 +975,17 @@ function attribute(error, entry, inferred = true) {
955
975
  error.remedy
956
976
  );
957
977
  }
958
- function truncate(text) {
959
- return text.length <= LOG_BODY_CHARS ? text : `${text.slice(0, LOG_BODY_CHARS)}\u2026 [+${text.length - LOG_BODY_CHARS} chars not logged]`;
978
+ function frameBodyNotLoggedNote(serializedFrame) {
979
+ const bytes = Buffer.byteLength(serializedFrame, "utf8");
980
+ const digest = createHash("sha256").update(serializedFrame, "utf8").digest("hex").slice(0, 12);
981
+ return `a ${bytes}-byte frame (sha256 ${digest}) whose text is not written to this log: on this socket a frame body is on-screen accessibility content \u2014 element titles and values, sometimes a document's text \u2014 and this log's sink is a file this product never sets the mode of, so the state root's 0700 does not cover it. Anything the daemon did record is in its evidence archive under the state root, read back with gp_last_evidence {operationId} or gp_export_evidence {operationId}`;
982
+ }
983
+ function shortFieldValue(value) {
984
+ const text = JSON.stringify(value) ?? String(value);
985
+ if (text.length <= LOG_FIELD_CHARS) return text;
986
+ const bytes = Buffer.byteLength(text, "utf8");
987
+ const digest = createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
988
+ return `${text.length}-char value (sha256 ${digest}, ${bytes} bytes) not quoted here`;
960
989
  }
961
990
  var ARCHIVE_OPERATION_ID = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
962
991
  function lateReplyBodyNote(serializedBody, operationId) {
@@ -991,8 +1020,8 @@ var ReconnectingSocketIo = class {
991
1020
  closeHandler = null;
992
1021
  errorHandler = null;
993
1022
  openHandler = null;
994
- writeLine(line) {
995
- this.connect().writeLine(line);
1023
+ writeLine(line, onHandedOff) {
1024
+ this.connect().writeLine(line, onHandedOff);
996
1025
  }
997
1026
  bufferedBytes() {
998
1027
  return this.inner?.bufferedBytes() ?? 0;
@@ -3070,7 +3099,7 @@ var TOOL_SPECS = [
3070
3099
  },
3071
3100
  {
3072
3101
  name: "gp_probe_status",
3073
- 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. 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.",
3102
+ 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. A duration the probe read but this wire cannot carry is the fourth loss with its own reading: `durationOverflowFrames` on a live row counts the `handlerDurationOverflow` frames this daemon ingested for that pid, `durationOverflowCount` on the same row is the probe's own lifetime figure (**absent when the probe never reported one**, which is not a measured zero), and `durationOverflowFramesTotal` is the process-wide count that survives the disconnect. Those frames are lost readings, not protocol violations: they never enter the event ring, so they never raise `hitCount`, and they are counted apart from the daemon's malformed frames \u2014 a `hitCount` of 0 beside a nonzero overflow count means the slow call happened and only its duration was unreadable. 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.",
3074
3103
  engineMethod: "probe_status",
3075
3104
  inputSchema: {
3076
3105
  type: "object",
@@ -3914,6 +3943,7 @@ function createHttpGateway(options) {
3914
3943
  } catch {
3915
3944
  }
3916
3945
  });
3946
+ setGatewayReportSink(report);
3917
3947
  const client = options.connectController !== void 0 ? options.connectController(options.socketPath) : unixSocketEngineClient(options.socketPath, { surface: "http" });
3918
3948
  client.onEngineNote?.((note) => report(`engine: ${note}`));
3919
3949
  client.onLateReply?.(({ method, result }) => {
@@ -3923,7 +3953,14 @@ function createHttpGateway(options) {
3923
3953
  const bodyReadTimeoutMs = options.bodyReadTimeoutMs ?? DEFAULT_BODY_READ_TIMEOUT_MS;
3924
3954
  const server = http.createServer((req, res) => {
3925
3955
  handleHttp(req, res, client, expectedToken, bodyReadTimeoutMs).catch((error) => {
3926
- fail(res, 500, GP_E_INTERNAL, `internal gateway error: ${String(error)}`, gatewayFaultAdvice());
3956
+ report(`internal gateway error for ${req.method} ${req.url}: ${String(error)}`);
3957
+ fail(
3958
+ res,
3959
+ 500,
3960
+ GP_E_INTERNAL,
3961
+ `internal gateway error of type ${errorTypeName(error)}; its own description names files this frame does not publish`,
3962
+ gatewayFaultAdvice()
3963
+ );
3927
3964
  });
3928
3965
  });
3929
3966
  server.listen(port, host);
@@ -3994,6 +4031,33 @@ function assertTokenPolicy(token) {
3994
4031
  );
3995
4032
  }
3996
4033
  }
4034
+ function errorTypeName(error) {
4035
+ if (error instanceof Error) {
4036
+ const name = error.constructor?.name;
4037
+ return typeof name === "string" && name.length > 0 ? name : "Error";
4038
+ }
4039
+ if (error === null) return "null";
4040
+ if (error === void 0) return "undefined";
4041
+ return typeof error;
4042
+ }
4043
+ var gatewayReportSink = reportToFallbackStderr;
4044
+ function setGatewayReportSink(sink) {
4045
+ gatewayReportSink = sink;
4046
+ }
4047
+ function reportToFallbackStderr(note) {
4048
+ try {
4049
+ process.stderr.write(`${note}
4050
+ `);
4051
+ } catch {
4052
+ }
4053
+ }
4054
+ function wireCause(where, error) {
4055
+ const type = errorTypeName(error);
4056
+ gatewayReportSink(
4057
+ `${where}: internal ${type} \u2014 ${String(error)} (withheld from the HTTP frame: a description of an internal failure names files this frame does not publish)`
4058
+ );
4059
+ return `an internal ${type} failure inside this gateway, at ${where}; its own description is on the gateway's stderr, not in this frame`;
4060
+ }
3997
4061
  function stringifyReply(result) {
3998
4062
  try {
3999
4063
  const text = JSON.stringify(result);
@@ -4204,7 +4268,7 @@ async function handleEvidenceAggregate(url, client, res) {
4204
4268
  operationId,
4205
4269
  kind: "frame",
4206
4270
  error,
4207
- line: `${GP_E_INTERNAL}: the daemon returned a last_evidence frame this gateway cannot render (no parseable evidencePack for ${operationId}: ${boundedCause(describeCause(error))})`
4271
+ line: `${GP_E_INTERNAL}: the daemon returned a last_evidence frame this gateway cannot render (no parseable evidencePack for ${operationId}: ${wireCause("the last_evidence fan-out", error)})`
4208
4272
  };
4209
4273
  notFetched.push(...ids.slice(index + 1));
4210
4274
  break;
@@ -4485,17 +4549,11 @@ function makeNotFetchedNote(notFetched, format) {
4485
4549
  return format === "html" ? `<p class="gp-not-fetched">${escapeHTML(sentence)}</p>` : `> ${sentence}`;
4486
4550
  }
4487
4551
  var CAUSE_MAX_CHARS = 400;
4488
- function describeCause(error) {
4489
- if (error instanceof Error) {
4490
- return error.message.trim() === "" ? error.name : error.message;
4491
- }
4492
- return String(error);
4493
- }
4494
4552
  function boundedCause(text) {
4495
4553
  return text.length <= CAUSE_MAX_CHARS ? text : `${text.slice(0, CAUSE_MAX_CHARS)}\u2026 [+${text.length - CAUSE_MAX_CHARS} chars not shown]`;
4496
4554
  }
4497
4555
  function engineFailureLine(error) {
4498
- return error instanceof EngineCallError ? `${error.code}: ${boundedCause(error.message)}` : `${GP_E_INTERNAL}: ${boundedCause(describeCause(error))}`;
4556
+ return error instanceof EngineCallError ? `${error.code}: ${boundedCause(error.message)}` : `${GP_E_INTERNAL}: ${wireCause("an engine call inside the partial report", error)}`;
4499
4557
  }
4500
4558
  function notFetchedTail(notFetched) {
4501
4559
  if (notFetched.length === 0) {
@@ -4597,7 +4655,7 @@ async function failEngine(res, error, spec, params, tail = "") {
4597
4655
  res,
4598
4656
  500,
4599
4657
  GP_E_INTERNAL,
4600
- `this gateway could not complete the request: ${String(error)}${tail}`,
4658
+ `this gateway could not complete the request: ${wireCause(`the ${spec?.name ?? "tool"} route handler`, error)}${tail}`,
4601
4659
  gatewayFaultAdvice(spec)
4602
4660
  );
4603
4661
  }
@@ -4633,7 +4691,7 @@ function failEvidenceFrameShape(res, error, operationId, tail = "") {
4633
4691
  res,
4634
4692
  502,
4635
4693
  GP_E_INTERNAL,
4636
- `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${String(error)})${tail}`,
4694
+ `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${wireCause("the last_evidence frame parser", error)})${tail}`,
4637
4695
  "the daemon answered this request, so the transport is up and restarting it changes nothing here; this gateway validates a pack before rendering or forwarding it, so GET /v1/evidence/<operationId> and POST /v1/tools/last_evidence {operationId} will both refuse this frame for the same reason. Read what the attached app is doing now without performing anything: POST /v1/tools/observe, POST /v1/tools/assert_element or POST /v1/tools/probe_status. Producing a fresh pack for this operation means acting again, which is a decision this read cannot make for you."
4638
4696
  );
4639
4697
  }
@@ -162,6 +162,9 @@ export declare function isLoopbackHost(value: string): boolean;
162
162
  export declare function assertLoopbackHost(host: string): string;
163
163
  /** Refuse an empty token, and one too short or too uniform to be a credential. */
164
164
  export declare function assertTokenPolicy(token: string): void;
165
+ /** Install the sink. Exported for the gateway factory; a caller that replaces it gets
166
+ * the last writer, which is what a single-process gateway already is. */
167
+ export declare function setGatewayReportSink(sink: (note: string) => void): void;
165
168
  /** How long one request body may take, when the caller did not choose (see {@link HttpGatewayOptions.bodyReadTimeoutMs}). */
166
169
  export declare const DEFAULT_BODY_READ_TIMEOUT_MS = 15000;
167
170
  //# sourceMappingURL=http-gateway.d.ts.map
@@ -123,8 +123,17 @@ var StreamLineIo = class {
123
123
  messageHandler = null;
124
124
  closeHandler = null;
125
125
  errorHandler = null;
126
- writeLine(line) {
127
- this.output.write(line + "\n");
126
+ writeLine(line, onHandedOff) {
127
+ const text = line + "\n";
128
+ if (onHandedOff === void 0) {
129
+ this.output.write(text);
130
+ return;
131
+ }
132
+ this.output.write(text, (error) => {
133
+ if (!error) {
134
+ onHandedOff();
135
+ }
136
+ });
128
137
  }
129
138
  bufferedBytes() {
130
139
  return this.output.writableLength;
@@ -375,7 +384,7 @@ function slowEngineRemedy(method, surface = "mcp") {
375
384
  return `${poll}. The daemon serves one request at a time and is still working on this one, so ${reIssueGuidance(surface)}; a restart is authorised only by ${restarted}`;
376
385
  }
377
386
  var LATE_REPLY_RETENTION = 16;
378
- var LOG_BODY_CHARS = 64 * 1024;
387
+ var LOG_FIELD_CHARS = 120;
379
388
  var EngineJsonRpcClient = class {
380
389
  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
381
390
  this.io = io;
@@ -529,7 +538,6 @@ var EngineJsonRpcClient = class {
529
538
  entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
530
539
  const backlog = this.io.bufferedBytes?.() ?? 0;
531
540
  if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
532
- this.pending.delete(id);
533
541
  this.reject(entry, new EngineCallError(
534
542
  GP_E_ENGINE_BACKLOG,
535
543
  `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
@@ -541,8 +549,12 @@ var EngineJsonRpcClient = class {
541
549
  const queuedBefore = this.io.bufferedBytes?.() ?? null;
542
550
  try {
543
551
  const frameText = JSON.stringify(frame);
544
- this.io.writeLine(frameText);
545
- if (queuedBefore !== null) {
552
+ let writeHandedOffConfirmed = false;
553
+ this.io.writeLine(frameText, () => {
554
+ writeHandedOffConfirmed = true;
555
+ entry.handedOff = true;
556
+ });
557
+ if (queuedBefore !== null && !writeHandedOffConfirmed) {
546
558
  const queuedAfter = this.io.bufferedBytes?.() ?? 0;
547
559
  entry.handedOff = queuedAfter < queuedBefore + frameText.length + 1;
548
560
  }
@@ -573,7 +585,8 @@ var EngineJsonRpcClient = class {
573
585
  this.report(
574
586
  `engine has not answered '${entry.method}' (id ${entry.id}) within ${entry.deadlineMs}ms \u2014 still in flight`
575
587
  );
576
- const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for an MCP client's sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
588
+ const waitingFor = this.surface === "mcp" ? "an MCP client" : "an HTTP caller";
589
+ const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for ${waitingFor}'s sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
577
590
  this.reject(entry, new EngineCallError(
578
591
  GP_E_ENGINE_TIMEOUT,
579
592
  `engine is still working on '${entry.method}': no reply after ${entry.deadlineMs}ms. The request stays registered \u2014 a late reply is written to the server log \u2014 so this is a busy or slow daemon, not an unreachable one. That registration lasts only while this connection does: if the transport ends first, the server log says so and names what it stopped tracking.` + capped,
@@ -602,11 +615,11 @@ var EngineJsonRpcClient = class {
602
615
  try {
603
616
  parsed = JSON.parse(line);
604
617
  } catch {
605
- this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
618
+ this.report(`engine sent a non-JSON frame, dropped: ${frameBodyNotLoggedNote(line)}`);
606
619
  return;
607
620
  }
608
621
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
609
- this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
622
+ this.report(`engine sent a frame that is not a JSON object, dropped: ${frameBodyNotLoggedNote(line)}`);
610
623
  return;
611
624
  }
612
625
  const frame = parsed;
@@ -617,7 +630,7 @@ var EngineJsonRpcClient = class {
617
630
  const tracked = [...this.pending.values()];
618
631
  const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
619
632
  this.report(
620
- `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
633
+ `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + frameBodyNotLoggedNote(line)
621
634
  );
622
635
  return;
623
636
  }
@@ -644,13 +657,13 @@ var EngineJsonRpcClient = class {
644
657
  this.retainForLateReply();
645
658
  return;
646
659
  }
647
- this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
660
+ this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${frameBodyNotLoggedNote(line)}`);
648
661
  return;
649
662
  }
650
- this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${truncate(line)}` : `engine sent an id-less frame with no request in flight: ${truncate(line)}`);
663
+ this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${frameBodyNotLoggedNote(line)}` : `engine sent an id-less frame with no request in flight: ${frameBodyNotLoggedNote(line)}`);
651
664
  return;
652
665
  }
653
- this.report(`engine sent a frame with a non-numeric request id (${jsonOrString(id)}), which this client never issues: ${truncate(line)}`);
666
+ this.report(`engine sent a frame with a non-numeric request id (${shortFieldValue(id)}), which this client never issues: ${frameBodyNotLoggedNote(line)}`);
654
667
  }
655
668
  settleFromFrame(entry, frame) {
656
669
  if (frame.error) {
@@ -687,12 +700,19 @@ var EngineJsonRpcClient = class {
687
700
  this.report(`the engine's late reply to '${entry.method}' (id ${entry.id}) exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes), so its body could not be delivered even late${inferred ? " (attributed by arrival order: the frame's head carried no readable id)" : ""}`);
688
701
  return;
689
702
  }
690
- this.pending.delete(entry.id);
691
- this.reject(entry, attribute(new EngineCallError(
703
+ const failure = new EngineCallError(
692
704
  GP_E_PAYLOAD_TOO_LARGE,
693
705
  `the engine's reply to '${entry.method}' exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes) and was dropped; the connection is intact and other requests are unaffected`,
694
706
  "narrow this request or ask for less of it; the tool's own schema names the parameters that can shrink a reply, and this shell rewrites this line into that advice when it can (the transport layer deliberately does not guess them)"
695
- ), entry, inferred));
707
+ );
708
+ if (inferred) {
709
+ this.reject(entry, attribute(failure, entry));
710
+ entry.arrivalOrderConsumed = true;
711
+ this.retainForLateReply();
712
+ return;
713
+ }
714
+ this.pending.delete(entry.id);
715
+ this.reject(entry, attribute(failure, entry, false));
696
716
  }
697
717
  /**
698
718
  * The daemon's error frame, mapped into this shell's error.
@@ -907,8 +927,17 @@ function attribute(error, entry, inferred = true) {
907
927
  error.remedy
908
928
  );
909
929
  }
910
- function truncate(text) {
911
- return text.length <= LOG_BODY_CHARS ? text : `${text.slice(0, LOG_BODY_CHARS)}\u2026 [+${text.length - LOG_BODY_CHARS} chars not logged]`;
930
+ function frameBodyNotLoggedNote(serializedFrame) {
931
+ const bytes = Buffer.byteLength(serializedFrame, "utf8");
932
+ const digest = createHash("sha256").update(serializedFrame, "utf8").digest("hex").slice(0, 12);
933
+ return `a ${bytes}-byte frame (sha256 ${digest}) whose text is not written to this log: on this socket a frame body is on-screen accessibility content \u2014 element titles and values, sometimes a document's text \u2014 and this log's sink is a file this product never sets the mode of, so the state root's 0700 does not cover it. Anything the daemon did record is in its evidence archive under the state root, read back with gp_last_evidence {operationId} or gp_export_evidence {operationId}`;
934
+ }
935
+ function shortFieldValue(value) {
936
+ const text = JSON.stringify(value) ?? String(value);
937
+ if (text.length <= LOG_FIELD_CHARS) return text;
938
+ const bytes = Buffer.byteLength(text, "utf8");
939
+ const digest = createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
940
+ return `${text.length}-char value (sha256 ${digest}, ${bytes} bytes) not quoted here`;
912
941
  }
913
942
  var ARCHIVE_OPERATION_ID = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
914
943
  function lateReplyBodyNote(serializedBody, operationId) {
@@ -943,8 +972,8 @@ var ReconnectingSocketIo = class {
943
972
  closeHandler = null;
944
973
  errorHandler = null;
945
974
  openHandler = null;
946
- writeLine(line) {
947
- this.connect().writeLine(line);
975
+ writeLine(line, onHandedOff) {
976
+ this.connect().writeLine(line, onHandedOff);
948
977
  }
949
978
  bufferedBytes() {
950
979
  return this.inner?.bufferedBytes() ?? 0;
@@ -3016,7 +3045,7 @@ var TOOL_SPECS = [
3016
3045
  },
3017
3046
  {
3018
3047
  name: "gp_probe_status",
3019
- 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. 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.",
3048
+ 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. A duration the probe read but this wire cannot carry is the fourth loss with its own reading: `durationOverflowFrames` on a live row counts the `handlerDurationOverflow` frames this daemon ingested for that pid, `durationOverflowCount` on the same row is the probe's own lifetime figure (**absent when the probe never reported one**, which is not a measured zero), and `durationOverflowFramesTotal` is the process-wide count that survives the disconnect. Those frames are lost readings, not protocol violations: they never enter the event ring, so they never raise `hitCount`, and they are counted apart from the daemon's malformed frames \u2014 a `hitCount` of 0 beside a nonzero overflow count means the slow call happened and only its duration was unreadable. 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.",
3020
3049
  engineMethod: "probe_status",
3021
3050
  inputSchema: {
3022
3051
  type: "object",
@@ -3860,6 +3889,7 @@ function createHttpGateway(options) {
3860
3889
  } catch {
3861
3890
  }
3862
3891
  });
3892
+ setGatewayReportSink(report);
3863
3893
  const client = options.connectController !== void 0 ? options.connectController(options.socketPath) : unixSocketEngineClient(options.socketPath, { surface: "http" });
3864
3894
  client.onEngineNote?.((note) => report(`engine: ${note}`));
3865
3895
  client.onLateReply?.(({ method, result }) => {
@@ -3869,7 +3899,14 @@ function createHttpGateway(options) {
3869
3899
  const bodyReadTimeoutMs = options.bodyReadTimeoutMs ?? DEFAULT_BODY_READ_TIMEOUT_MS;
3870
3900
  const server = http.createServer((req, res) => {
3871
3901
  handleHttp(req, res, client, expectedToken, bodyReadTimeoutMs).catch((error) => {
3872
- fail(res, 500, GP_E_INTERNAL, `internal gateway error: ${String(error)}`, gatewayFaultAdvice());
3902
+ report(`internal gateway error for ${req.method} ${req.url}: ${String(error)}`);
3903
+ fail(
3904
+ res,
3905
+ 500,
3906
+ GP_E_INTERNAL,
3907
+ `internal gateway error of type ${errorTypeName(error)}; its own description names files this frame does not publish`,
3908
+ gatewayFaultAdvice()
3909
+ );
3873
3910
  });
3874
3911
  });
3875
3912
  server.listen(port, host);
@@ -3940,6 +3977,33 @@ function assertTokenPolicy(token) {
3940
3977
  );
3941
3978
  }
3942
3979
  }
3980
+ function errorTypeName(error) {
3981
+ if (error instanceof Error) {
3982
+ const name = error.constructor?.name;
3983
+ return typeof name === "string" && name.length > 0 ? name : "Error";
3984
+ }
3985
+ if (error === null) return "null";
3986
+ if (error === void 0) return "undefined";
3987
+ return typeof error;
3988
+ }
3989
+ var gatewayReportSink = reportToFallbackStderr;
3990
+ function setGatewayReportSink(sink) {
3991
+ gatewayReportSink = sink;
3992
+ }
3993
+ function reportToFallbackStderr(note) {
3994
+ try {
3995
+ process.stderr.write(`${note}
3996
+ `);
3997
+ } catch {
3998
+ }
3999
+ }
4000
+ function wireCause(where, error) {
4001
+ const type = errorTypeName(error);
4002
+ gatewayReportSink(
4003
+ `${where}: internal ${type} \u2014 ${String(error)} (withheld from the HTTP frame: a description of an internal failure names files this frame does not publish)`
4004
+ );
4005
+ return `an internal ${type} failure inside this gateway, at ${where}; its own description is on the gateway's stderr, not in this frame`;
4006
+ }
3943
4007
  function stringifyReply(result) {
3944
4008
  try {
3945
4009
  const text = JSON.stringify(result);
@@ -4150,7 +4214,7 @@ async function handleEvidenceAggregate(url, client, res) {
4150
4214
  operationId,
4151
4215
  kind: "frame",
4152
4216
  error,
4153
- line: `${GP_E_INTERNAL}: the daemon returned a last_evidence frame this gateway cannot render (no parseable evidencePack for ${operationId}: ${boundedCause(describeCause(error))})`
4217
+ line: `${GP_E_INTERNAL}: the daemon returned a last_evidence frame this gateway cannot render (no parseable evidencePack for ${operationId}: ${wireCause("the last_evidence fan-out", error)})`
4154
4218
  };
4155
4219
  notFetched.push(...ids.slice(index + 1));
4156
4220
  break;
@@ -4431,17 +4495,11 @@ function makeNotFetchedNote(notFetched, format) {
4431
4495
  return format === "html" ? `<p class="gp-not-fetched">${escapeHTML(sentence)}</p>` : `> ${sentence}`;
4432
4496
  }
4433
4497
  var CAUSE_MAX_CHARS = 400;
4434
- function describeCause(error) {
4435
- if (error instanceof Error) {
4436
- return error.message.trim() === "" ? error.name : error.message;
4437
- }
4438
- return String(error);
4439
- }
4440
4498
  function boundedCause(text) {
4441
4499
  return text.length <= CAUSE_MAX_CHARS ? text : `${text.slice(0, CAUSE_MAX_CHARS)}\u2026 [+${text.length - CAUSE_MAX_CHARS} chars not shown]`;
4442
4500
  }
4443
4501
  function engineFailureLine(error) {
4444
- return error instanceof EngineCallError ? `${error.code}: ${boundedCause(error.message)}` : `${GP_E_INTERNAL}: ${boundedCause(describeCause(error))}`;
4502
+ return error instanceof EngineCallError ? `${error.code}: ${boundedCause(error.message)}` : `${GP_E_INTERNAL}: ${wireCause("an engine call inside the partial report", error)}`;
4445
4503
  }
4446
4504
  function notFetchedTail(notFetched) {
4447
4505
  if (notFetched.length === 0) {
@@ -4543,7 +4601,7 @@ async function failEngine(res, error, spec, params, tail = "") {
4543
4601
  res,
4544
4602
  500,
4545
4603
  GP_E_INTERNAL,
4546
- `this gateway could not complete the request: ${String(error)}${tail}`,
4604
+ `this gateway could not complete the request: ${wireCause(`the ${spec?.name ?? "tool"} route handler`, error)}${tail}`,
4547
4605
  gatewayFaultAdvice(spec)
4548
4606
  );
4549
4607
  }
@@ -4579,7 +4637,7 @@ function failEvidenceFrameShape(res, error, operationId, tail = "") {
4579
4637
  res,
4580
4638
  502,
4581
4639
  GP_E_INTERNAL,
4582
- `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${String(error)})${tail}`,
4640
+ `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${wireCause("the last_evidence frame parser", error)})${tail}`,
4583
4641
  "the daemon answered this request, so the transport is up and restarting it changes nothing here; this gateway validates a pack before rendering or forwarding it, so GET /v1/evidence/<operationId> and POST /v1/tools/last_evidence {operationId} will both refuse this frame for the same reason. Read what the attached app is doing now without performing anything: POST /v1/tools/observe, POST /v1/tools/assert_element or POST /v1/tools/probe_status. Producing a fresh pack for this operation means acting again, which is a decision this read cannot make for you."
4584
4642
  );
4585
4643
  }
@@ -4650,5 +4708,6 @@ export {
4650
4708
  assertLoopbackHost,
4651
4709
  assertTokenPolicy,
4652
4710
  createHttpGateway,
4653
- isLoopbackHost
4711
+ isLoopbackHost,
4712
+ setGatewayReportSink
4654
4713
  };
package/dist/index.js CHANGED
@@ -1307,8 +1307,17 @@ var StreamLineIo = class {
1307
1307
  messageHandler = null;
1308
1308
  closeHandler = null;
1309
1309
  errorHandler = null;
1310
- writeLine(line) {
1311
- this.output.write(line + "\n");
1310
+ writeLine(line, onHandedOff) {
1311
+ const text = line + "\n";
1312
+ if (onHandedOff === void 0) {
1313
+ this.output.write(text);
1314
+ return;
1315
+ }
1316
+ this.output.write(text, (error) => {
1317
+ if (!error) {
1318
+ onHandedOff();
1319
+ }
1320
+ });
1312
1321
  }
1313
1322
  bufferedBytes() {
1314
1323
  return this.output.writableLength;
@@ -1683,7 +1692,7 @@ function slowEngineRemedy(method, surface = "mcp") {
1683
1692
  return `${poll}. The daemon serves one request at a time and is still working on this one, so ${reIssueGuidance(surface)}; a restart is authorised only by ${restarted}`;
1684
1693
  }
1685
1694
  var LATE_REPLY_RETENTION = 16;
1686
- var LOG_BODY_CHARS = 64 * 1024;
1695
+ var LOG_FIELD_CHARS = 120;
1687
1696
  var EngineJsonRpcClient = class {
1688
1697
  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
1689
1698
  this.io = io;
@@ -1837,7 +1846,6 @@ var EngineJsonRpcClient = class {
1837
1846
  entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
1838
1847
  const backlog = this.io.bufferedBytes?.() ?? 0;
1839
1848
  if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
1840
- this.pending.delete(id);
1841
1849
  this.reject(entry, new EngineCallError(
1842
1850
  GP_E_ENGINE_BACKLOG,
1843
1851
  `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
@@ -1849,8 +1857,12 @@ var EngineJsonRpcClient = class {
1849
1857
  const queuedBefore = this.io.bufferedBytes?.() ?? null;
1850
1858
  try {
1851
1859
  const frameText = JSON.stringify(frame);
1852
- this.io.writeLine(frameText);
1853
- if (queuedBefore !== null) {
1860
+ let writeHandedOffConfirmed = false;
1861
+ this.io.writeLine(frameText, () => {
1862
+ writeHandedOffConfirmed = true;
1863
+ entry.handedOff = true;
1864
+ });
1865
+ if (queuedBefore !== null && !writeHandedOffConfirmed) {
1854
1866
  const queuedAfter = this.io.bufferedBytes?.() ?? 0;
1855
1867
  entry.handedOff = queuedAfter < queuedBefore + frameText.length + 1;
1856
1868
  }
@@ -1881,7 +1893,8 @@ var EngineJsonRpcClient = class {
1881
1893
  this.report(
1882
1894
  `engine has not answered '${entry.method}' (id ${entry.id}) within ${entry.deadlineMs}ms \u2014 still in flight`
1883
1895
  );
1884
- const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for an MCP client's sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
1896
+ const waitingFor = this.surface === "mcp" ? "an MCP client" : "an HTTP caller";
1897
+ const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for ${waitingFor}'s sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
1885
1898
  this.reject(entry, new EngineCallError(
1886
1899
  GP_E_ENGINE_TIMEOUT,
1887
1900
  `engine is still working on '${entry.method}': no reply after ${entry.deadlineMs}ms. The request stays registered \u2014 a late reply is written to the server log \u2014 so this is a busy or slow daemon, not an unreachable one. That registration lasts only while this connection does: if the transport ends first, the server log says so and names what it stopped tracking.` + capped,
@@ -1910,11 +1923,11 @@ var EngineJsonRpcClient = class {
1910
1923
  try {
1911
1924
  parsed = JSON.parse(line);
1912
1925
  } catch {
1913
- this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
1926
+ this.report(`engine sent a non-JSON frame, dropped: ${frameBodyNotLoggedNote(line)}`);
1914
1927
  return;
1915
1928
  }
1916
1929
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
1917
- this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
1930
+ this.report(`engine sent a frame that is not a JSON object, dropped: ${frameBodyNotLoggedNote(line)}`);
1918
1931
  return;
1919
1932
  }
1920
1933
  const frame = parsed;
@@ -1925,7 +1938,7 @@ var EngineJsonRpcClient = class {
1925
1938
  const tracked = [...this.pending.values()];
1926
1939
  const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
1927
1940
  this.report(
1928
- `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
1941
+ `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + frameBodyNotLoggedNote(line)
1929
1942
  );
1930
1943
  return;
1931
1944
  }
@@ -1952,13 +1965,13 @@ var EngineJsonRpcClient = class {
1952
1965
  this.retainForLateReply();
1953
1966
  return;
1954
1967
  }
1955
- this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
1968
+ this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${frameBodyNotLoggedNote(line)}`);
1956
1969
  return;
1957
1970
  }
1958
- this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${truncate(line)}` : `engine sent an id-less frame with no request in flight: ${truncate(line)}`);
1971
+ this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${frameBodyNotLoggedNote(line)}` : `engine sent an id-less frame with no request in flight: ${frameBodyNotLoggedNote(line)}`);
1959
1972
  return;
1960
1973
  }
1961
- this.report(`engine sent a frame with a non-numeric request id (${jsonOrString(id)}), which this client never issues: ${truncate(line)}`);
1974
+ this.report(`engine sent a frame with a non-numeric request id (${shortFieldValue(id)}), which this client never issues: ${frameBodyNotLoggedNote(line)}`);
1962
1975
  }
1963
1976
  settleFromFrame(entry, frame) {
1964
1977
  if (frame.error) {
@@ -1995,12 +2008,19 @@ var EngineJsonRpcClient = class {
1995
2008
  this.report(`the engine's late reply to '${entry.method}' (id ${entry.id}) exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes), so its body could not be delivered even late${inferred ? " (attributed by arrival order: the frame's head carried no readable id)" : ""}`);
1996
2009
  return;
1997
2010
  }
1998
- this.pending.delete(entry.id);
1999
- this.reject(entry, attribute(new EngineCallError(
2011
+ const failure = new EngineCallError(
2000
2012
  GP_E_PAYLOAD_TOO_LARGE,
2001
2013
  `the engine's reply to '${entry.method}' exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes) and was dropped; the connection is intact and other requests are unaffected`,
2002
2014
  "narrow this request or ask for less of it; the tool's own schema names the parameters that can shrink a reply, and this shell rewrites this line into that advice when it can (the transport layer deliberately does not guess them)"
2003
- ), entry, inferred));
2015
+ );
2016
+ if (inferred) {
2017
+ this.reject(entry, attribute(failure, entry));
2018
+ entry.arrivalOrderConsumed = true;
2019
+ this.retainForLateReply();
2020
+ return;
2021
+ }
2022
+ this.pending.delete(entry.id);
2023
+ this.reject(entry, attribute(failure, entry, false));
2004
2024
  }
2005
2025
  /**
2006
2026
  * The daemon's error frame, mapped into this shell's error.
@@ -2215,8 +2235,17 @@ function attribute(error, entry, inferred = true) {
2215
2235
  error.remedy
2216
2236
  );
2217
2237
  }
2218
- function truncate(text) {
2219
- return text.length <= LOG_BODY_CHARS ? text : `${text.slice(0, LOG_BODY_CHARS)}\u2026 [+${text.length - LOG_BODY_CHARS} chars not logged]`;
2238
+ function frameBodyNotLoggedNote(serializedFrame) {
2239
+ const bytes = Buffer.byteLength(serializedFrame, "utf8");
2240
+ const digest = createHash("sha256").update(serializedFrame, "utf8").digest("hex").slice(0, 12);
2241
+ return `a ${bytes}-byte frame (sha256 ${digest}) whose text is not written to this log: on this socket a frame body is on-screen accessibility content \u2014 element titles and values, sometimes a document's text \u2014 and this log's sink is a file this product never sets the mode of, so the state root's 0700 does not cover it. Anything the daemon did record is in its evidence archive under the state root, read back with gp_last_evidence {operationId} or gp_export_evidence {operationId}`;
2242
+ }
2243
+ function shortFieldValue(value) {
2244
+ const text = JSON.stringify(value) ?? String(value);
2245
+ if (text.length <= LOG_FIELD_CHARS) return text;
2246
+ const bytes = Buffer.byteLength(text, "utf8");
2247
+ const digest = createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
2248
+ return `${text.length}-char value (sha256 ${digest}, ${bytes} bytes) not quoted here`;
2220
2249
  }
2221
2250
  var ARCHIVE_OPERATION_ID = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
2222
2251
  function lateReplyBodyNote(serializedBody, operationId) {
@@ -2251,8 +2280,8 @@ var ReconnectingSocketIo = class {
2251
2280
  closeHandler = null;
2252
2281
  errorHandler = null;
2253
2282
  openHandler = null;
2254
- writeLine(line) {
2255
- this.connect().writeLine(line);
2283
+ writeLine(line, onHandedOff) {
2284
+ this.connect().writeLine(line, onHandedOff);
2256
2285
  }
2257
2286
  bufferedBytes() {
2258
2287
  return this.inner?.bufferedBytes() ?? 0;
@@ -3766,7 +3795,7 @@ var TOOL_SPECS = [
3766
3795
  },
3767
3796
  {
3768
3797
  name: "gp_probe_status",
3769
- 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. 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.",
3798
+ 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. A duration the probe read but this wire cannot carry is the fourth loss with its own reading: `durationOverflowFrames` on a live row counts the `handlerDurationOverflow` frames this daemon ingested for that pid, `durationOverflowCount` on the same row is the probe's own lifetime figure (**absent when the probe never reported one**, which is not a measured zero), and `durationOverflowFramesTotal` is the process-wide count that survives the disconnect. Those frames are lost readings, not protocol violations: they never enter the event ring, so they never raise `hitCount`, and they are counted apart from the daemon's malformed frames \u2014 a `hitCount` of 0 beside a nonzero overflow count means the slow call happened and only its duration was unreadable. 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.",
3770
3799
  engineMethod: "probe_status",
3771
3800
  inputSchema: {
3772
3801
  type: "object",
@@ -4837,7 +4866,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
4837
4866
  "2025-03-26",
4838
4867
  MCP_PROTOCOL_VERSION
4839
4868
  ];
4840
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.24.1" };
4869
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.26.0" };
4841
4870
  var PARSE_ERROR = -32700;
4842
4871
  var INVALID_REQUEST = -32600;
4843
4872
  var METHOD_NOT_FOUND = -32601;
package/dist/io.d.ts CHANGED
@@ -90,7 +90,21 @@ export declare function recoverFrameId(prefix: string): number | string | null;
90
90
  * a Unix socket; tests inject an in-memory fake transport.
91
91
  */
92
92
  export interface LineIo {
93
- writeLine(line: string): void;
93
+ /**
94
+ * Write one newline-terminated frame.
95
+ *
96
+ * @param onHandedOff optional. A transport that can tell *when* the bytes
97
+ * actually left this process (the flush callback of its write) calls this with
98
+ * no error. It is the temporal half of the hand-off question that
99
+ * `bufferedBytes()` answers statically (S1-1): a frame whose bytes sat in the
100
+ * local send queue at write time and drained out afterwards is a frame the
101
+ * daemon could have executed, and a transport that goes away after that may
102
+ * not claim "nothing left this process". Transports that never call it —
103
+ * every in-memory fake written before this parameter existed — leave the
104
+ * verdict to the static measurement, which is why the callback only ever
105
+ * *raises* `handedOff`, never lowers it.
106
+ */
107
+ writeLine(line: string, onHandedOff?: () => void): void;
94
108
  /**
95
109
  * 已经交给内核、还没被对端读走的字节数。可选:只有真的接在一条 socket/pipe 上
96
110
  * 的传输量得出这个数。
@@ -124,7 +138,7 @@ export declare class StreamLineIo implements LineIo {
124
138
  private closeHandler;
125
139
  private errorHandler;
126
140
  constructor(input: Readable, output: Writable);
127
- writeLine(line: string): void;
141
+ writeLine(line: string, onHandedOff?: () => void): void;
128
142
  bufferedBytes(): number;
129
143
  onMessage(handler: (line: string) => void): void;
130
144
  onClose(handler: () => void): void;
@@ -1302,8 +1302,17 @@ var StreamLineIo = class {
1302
1302
  messageHandler = null;
1303
1303
  closeHandler = null;
1304
1304
  errorHandler = null;
1305
- writeLine(line) {
1306
- this.output.write(line + "\n");
1305
+ writeLine(line, onHandedOff) {
1306
+ const text = line + "\n";
1307
+ if (onHandedOff === void 0) {
1308
+ this.output.write(text);
1309
+ return;
1310
+ }
1311
+ this.output.write(text, (error) => {
1312
+ if (!error) {
1313
+ onHandedOff();
1314
+ }
1315
+ });
1307
1316
  }
1308
1317
  bufferedBytes() {
1309
1318
  return this.output.writableLength;
@@ -1678,7 +1687,7 @@ function slowEngineRemedy(method, surface = "mcp") {
1678
1687
  return `${poll}. The daemon serves one request at a time and is still working on this one, so ${reIssueGuidance(surface)}; a restart is authorised only by ${restarted}`;
1679
1688
  }
1680
1689
  var LATE_REPLY_RETENTION = 16;
1681
- var LOG_BODY_CHARS = 64 * 1024;
1690
+ var LOG_FIELD_CHARS = 120;
1682
1691
  var EngineJsonRpcClient = class {
1683
1692
  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
1684
1693
  this.io = io;
@@ -1832,7 +1841,6 @@ var EngineJsonRpcClient = class {
1832
1841
  entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
1833
1842
  const backlog = this.io.bufferedBytes?.() ?? 0;
1834
1843
  if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
1835
- this.pending.delete(id);
1836
1844
  this.reject(entry, new EngineCallError(
1837
1845
  GP_E_ENGINE_BACKLOG,
1838
1846
  `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
@@ -1844,8 +1852,12 @@ var EngineJsonRpcClient = class {
1844
1852
  const queuedBefore = this.io.bufferedBytes?.() ?? null;
1845
1853
  try {
1846
1854
  const frameText = JSON.stringify(frame);
1847
- this.io.writeLine(frameText);
1848
- if (queuedBefore !== null) {
1855
+ let writeHandedOffConfirmed = false;
1856
+ this.io.writeLine(frameText, () => {
1857
+ writeHandedOffConfirmed = true;
1858
+ entry.handedOff = true;
1859
+ });
1860
+ if (queuedBefore !== null && !writeHandedOffConfirmed) {
1849
1861
  const queuedAfter = this.io.bufferedBytes?.() ?? 0;
1850
1862
  entry.handedOff = queuedAfter < queuedBefore + frameText.length + 1;
1851
1863
  }
@@ -1876,7 +1888,8 @@ var EngineJsonRpcClient = class {
1876
1888
  this.report(
1877
1889
  `engine has not answered '${entry.method}' (id ${entry.id}) within ${entry.deadlineMs}ms \u2014 still in flight`
1878
1890
  );
1879
- const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for an MCP client's sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
1891
+ const waitingFor = this.surface === "mcp" ? "an MCP client" : "an HTTP caller";
1892
+ const capped = entry.methodDeadlineMs > entry.deadlineMs ? ` This shell stops waiting for ${waitingFor}'s sake at ${entry.deadlineMs}ms while the daemon gets up to ${entry.methodDeadlineMs}ms for '${entry.method}', because a client that is left hanging retries on its own and a retried '${entry.method}' runs twice.` : "";
1880
1893
  this.reject(entry, new EngineCallError(
1881
1894
  GP_E_ENGINE_TIMEOUT,
1882
1895
  `engine is still working on '${entry.method}': no reply after ${entry.deadlineMs}ms. The request stays registered \u2014 a late reply is written to the server log \u2014 so this is a busy or slow daemon, not an unreachable one. That registration lasts only while this connection does: if the transport ends first, the server log says so and names what it stopped tracking.` + capped,
@@ -1905,11 +1918,11 @@ var EngineJsonRpcClient = class {
1905
1918
  try {
1906
1919
  parsed = JSON.parse(line);
1907
1920
  } catch {
1908
- this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
1921
+ this.report(`engine sent a non-JSON frame, dropped: ${frameBodyNotLoggedNote(line)}`);
1909
1922
  return;
1910
1923
  }
1911
1924
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
1912
- this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
1925
+ this.report(`engine sent a frame that is not a JSON object, dropped: ${frameBodyNotLoggedNote(line)}`);
1913
1926
  return;
1914
1927
  }
1915
1928
  const frame = parsed;
@@ -1920,7 +1933,7 @@ var EngineJsonRpcClient = class {
1920
1933
  const tracked = [...this.pending.values()];
1921
1934
  const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
1922
1935
  this.report(
1923
- `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
1936
+ `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + frameBodyNotLoggedNote(line)
1924
1937
  );
1925
1938
  return;
1926
1939
  }
@@ -1947,13 +1960,13 @@ var EngineJsonRpcClient = class {
1947
1960
  this.retainForLateReply();
1948
1961
  return;
1949
1962
  }
1950
- this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
1963
+ this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${frameBodyNotLoggedNote(line)}`);
1951
1964
  return;
1952
1965
  }
1953
- this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${truncate(line)}` : `engine sent an id-less frame with no request in flight: ${truncate(line)}`);
1966
+ this.report(frame.error ? `engine reported ${this.engineError(frame.error, null).code} with no request in flight: ${frameBodyNotLoggedNote(line)}` : `engine sent an id-less frame with no request in flight: ${frameBodyNotLoggedNote(line)}`);
1954
1967
  return;
1955
1968
  }
1956
- this.report(`engine sent a frame with a non-numeric request id (${jsonOrString(id)}), which this client never issues: ${truncate(line)}`);
1969
+ this.report(`engine sent a frame with a non-numeric request id (${shortFieldValue(id)}), which this client never issues: ${frameBodyNotLoggedNote(line)}`);
1957
1970
  }
1958
1971
  settleFromFrame(entry, frame) {
1959
1972
  if (frame.error) {
@@ -1990,12 +2003,19 @@ var EngineJsonRpcClient = class {
1990
2003
  this.report(`the engine's late reply to '${entry.method}' (id ${entry.id}) exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes), so its body could not be delivered even late${inferred ? " (attributed by arrival order: the frame's head carried no readable id)" : ""}`);
1991
2004
  return;
1992
2005
  }
1993
- this.pending.delete(entry.id);
1994
- this.reject(entry, attribute(new EngineCallError(
2006
+ const failure = new EngineCallError(
1995
2007
  GP_E_PAYLOAD_TOO_LARGE,
1996
2008
  `the engine's reply to '${entry.method}' exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes) and was dropped; the connection is intact and other requests are unaffected`,
1997
2009
  "narrow this request or ask for less of it; the tool's own schema names the parameters that can shrink a reply, and this shell rewrites this line into that advice when it can (the transport layer deliberately does not guess them)"
1998
- ), entry, inferred));
2010
+ );
2011
+ if (inferred) {
2012
+ this.reject(entry, attribute(failure, entry));
2013
+ entry.arrivalOrderConsumed = true;
2014
+ this.retainForLateReply();
2015
+ return;
2016
+ }
2017
+ this.pending.delete(entry.id);
2018
+ this.reject(entry, attribute(failure, entry, false));
1999
2019
  }
2000
2020
  /**
2001
2021
  * The daemon's error frame, mapped into this shell's error.
@@ -2210,8 +2230,17 @@ function attribute(error, entry, inferred = true) {
2210
2230
  error.remedy
2211
2231
  );
2212
2232
  }
2213
- function truncate(text) {
2214
- return text.length <= LOG_BODY_CHARS ? text : `${text.slice(0, LOG_BODY_CHARS)}\u2026 [+${text.length - LOG_BODY_CHARS} chars not logged]`;
2233
+ function frameBodyNotLoggedNote(serializedFrame) {
2234
+ const bytes = Buffer.byteLength(serializedFrame, "utf8");
2235
+ const digest = createHash("sha256").update(serializedFrame, "utf8").digest("hex").slice(0, 12);
2236
+ return `a ${bytes}-byte frame (sha256 ${digest}) whose text is not written to this log: on this socket a frame body is on-screen accessibility content \u2014 element titles and values, sometimes a document's text \u2014 and this log's sink is a file this product never sets the mode of, so the state root's 0700 does not cover it. Anything the daemon did record is in its evidence archive under the state root, read back with gp_last_evidence {operationId} or gp_export_evidence {operationId}`;
2237
+ }
2238
+ function shortFieldValue(value) {
2239
+ const text = JSON.stringify(value) ?? String(value);
2240
+ if (text.length <= LOG_FIELD_CHARS) return text;
2241
+ const bytes = Buffer.byteLength(text, "utf8");
2242
+ const digest = createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
2243
+ return `${text.length}-char value (sha256 ${digest}, ${bytes} bytes) not quoted here`;
2215
2244
  }
2216
2245
  var ARCHIVE_OPERATION_ID = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
2217
2246
  function lateReplyBodyNote(serializedBody, operationId) {
@@ -2246,8 +2275,8 @@ var ReconnectingSocketIo = class {
2246
2275
  closeHandler = null;
2247
2276
  errorHandler = null;
2248
2277
  openHandler = null;
2249
- writeLine(line) {
2250
- this.connect().writeLine(line);
2278
+ writeLine(line, onHandedOff) {
2279
+ this.connect().writeLine(line, onHandedOff);
2251
2280
  }
2252
2281
  bufferedBytes() {
2253
2282
  return this.inner?.bufferedBytes() ?? 0;
@@ -3761,7 +3790,7 @@ var TOOL_SPECS = [
3761
3790
  },
3762
3791
  {
3763
3792
  name: "gp_probe_status",
3764
- 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. 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.",
3793
+ 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` / `droppedInboundFrames` / `droppedInboundLines` 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. Two more daemon-side losses are readable here: `ringEvictedEvents` on a live row (that pid's events dropped when its 512-event ring overflowed) and `ringEvictedEventsTotal` for the process \u2014 a nonzero one means that window's `hitCount` and `handlers` are a **lower bound**, not a complete measurement, and the archived pack carries the same caveat under `circuitBreaker.reason`. A duration the probe read but this wire cannot carry is the fourth loss with its own reading: `durationOverflowFrames` on a live row counts the `handlerDurationOverflow` frames this daemon ingested for that pid, `durationOverflowCount` on the same row is the probe's own lifetime figure (**absent when the probe never reported one**, which is not a measured zero), and `durationOverflowFramesTotal` is the process-wide count that survives the disconnect. Those frames are lost readings, not protocol violations: they never enter the event ring, so they never raise `hitCount`, and they are counted apart from the daemon's malformed frames \u2014 a `hitCount` of 0 beside a nonzero overflow count means the slow call happened and only its duration was unreadable. 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.",
3765
3794
  engineMethod: "probe_status",
3766
3795
  inputSchema: {
3767
3796
  type: "object",
@@ -4832,7 +4861,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
4832
4861
  "2025-03-26",
4833
4862
  MCP_PROTOCOL_VERSION
4834
4863
  ];
4835
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.24.1" };
4864
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.26.0" };
4836
4865
  var PARSE_ERROR = -32700;
4837
4866
  var INVALID_REQUEST = -32600;
4838
4867
  var METHOD_NOT_FOUND = -32601;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glasspane-mcp",
3
- "version": "1.24.1",
3
+ "version": "1.26.0",
4
4
  "description": "GlassPane MCP stdio shell: JSON-RPC 2.0 over stdio bridging an AI agent to the glasspane engine daemon",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",