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 +5 -2
- package/dist/dispatch.d.ts +1 -1
- package/dist/engine-client.d.ts +32 -3
- package/dist/http-gateway-cli.js +90 -32
- package/dist/http-gateway.d.ts +3 -0
- package/dist/http-gateway.js +92 -33
- package/dist/index.js +51 -22
- package/dist/io.d.ts +16 -2
- package/dist/stdio-session.js +51 -22
- package/package.json +1 -1
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
|
-
|
|
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
|
|
package/dist/dispatch.d.ts
CHANGED
|
@@ -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.
|
|
29
|
+
readonly version: "1.26.0";
|
|
30
30
|
};
|
|
31
31
|
export declare const PARSE_ERROR = -32700;
|
|
32
32
|
export declare const INVALID_REQUEST = -32600;
|
package/dist/engine-client.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
package/dist/http-gateway-cli.js
CHANGED
|
@@ -150,8 +150,17 @@ var StreamLineIo = class {
|
|
|
150
150
|
messageHandler = null;
|
|
151
151
|
closeHandler = null;
|
|
152
152
|
errorHandler = null;
|
|
153
|
-
writeLine(line) {
|
|
154
|
-
|
|
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
|
|
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
|
-
|
|
593
|
-
|
|
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
|
|
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: ${
|
|
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: ${
|
|
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 + ": " +
|
|
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: ${
|
|
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: ${
|
|
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 (${
|
|
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
|
-
|
|
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
|
-
)
|
|
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
|
|
959
|
-
|
|
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
|
-
|
|
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}: ${
|
|
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}: ${
|
|
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: ${
|
|
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}`}: ${
|
|
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
|
}
|
package/dist/http-gateway.d.ts
CHANGED
|
@@ -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
|
package/dist/http-gateway.js
CHANGED
|
@@ -123,8 +123,17 @@ var StreamLineIo = class {
|
|
|
123
123
|
messageHandler = null;
|
|
124
124
|
closeHandler = null;
|
|
125
125
|
errorHandler = null;
|
|
126
|
-
writeLine(line) {
|
|
127
|
-
|
|
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
|
|
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
|
-
|
|
545
|
-
|
|
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
|
|
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: ${
|
|
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: ${
|
|
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 + ": " +
|
|
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: ${
|
|
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: ${
|
|
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 (${
|
|
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
|
-
|
|
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
|
-
)
|
|
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
|
|
911
|
-
|
|
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
|
-
|
|
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}: ${
|
|
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}: ${
|
|
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: ${
|
|
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}`}: ${
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
1853
|
-
|
|
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
|
|
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: ${
|
|
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: ${
|
|
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 + ": " +
|
|
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: ${
|
|
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: ${
|
|
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 (${
|
|
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
|
-
|
|
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
|
-
)
|
|
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
|
|
2219
|
-
|
|
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.
|
|
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
|
-
|
|
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;
|
package/dist/stdio-session.js
CHANGED
|
@@ -1302,8 +1302,17 @@ var StreamLineIo = class {
|
|
|
1302
1302
|
messageHandler = null;
|
|
1303
1303
|
closeHandler = null;
|
|
1304
1304
|
errorHandler = null;
|
|
1305
|
-
writeLine(line) {
|
|
1306
|
-
|
|
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
|
|
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
|
-
|
|
1848
|
-
|
|
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
|
|
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: ${
|
|
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: ${
|
|
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 + ": " +
|
|
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: ${
|
|
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: ${
|
|
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 (${
|
|
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
|
-
|
|
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
|
-
)
|
|
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
|
|
2214
|
-
|
|
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.
|
|
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