glasspane-mcp 1.25.2 → 1.27.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.25.2";
29
+ readonly version: "1.27.0";
30
30
  };
31
31
  export declare const PARSE_ERROR = -32700;
32
32
  export declare const INVALID_REQUEST = -32600;
@@ -89,6 +89,21 @@ export declare class McpServer {
89
89
  */
90
90
  private negotiateProtocolVersion;
91
91
  private callTool;
92
+ /**
93
+ * The name the fault remedy should be written about: the **engine method**, when the frame
94
+ * names a tool this server publishes.
95
+ *
96
+ * `shellFaultRemedy` branches on the engine method (`act` / `restore` / `attach` are the
97
+ * replay-unsafe ones — see `REPLAY_UNSAFE_REASONS` in engine-client.ts), and a tool name is
98
+ * not an engine method: `gp_act` is not in that table, so handing it over answered a fault
99
+ * inside `gp_act` with "sending this tool again is a real option — do that once". That is
100
+ * the one sentence this product refuses to print for an action that may still be performing
101
+ * a change on the user's screen, so the domain conversion happens here, at the only call
102
+ * site. An unknown name is not a method either, and the caller's own bytes must not be
103
+ * echoed unbounded into the remedy, so that arm falls back to the protocol method — bounded
104
+ * and control-neutralised, the same rule {@link echoForeign} states.
105
+ */
106
+ private callTargetName;
92
107
  private asParams;
93
108
  private isRequestBody;
94
109
  private result;
@@ -97,10 +112,32 @@ export declare class McpServer {
97
112
  * actually answers. A JSON-RPC reader cannot open a source symbol, and an example naming a
98
113
  * tool this surface does not publish would be a second refusal waiting to happen — so the
99
114
  * preference is a published tool that is legal to call with an empty `arguments`.
100
- * `test/dispatch.test.mjs` checks every name in this sentence against `tools/list`, and
101
- * checks it again on a server deliberately built with a one-tool list.
115
+ *
116
+ * "Legal with an empty arguments" is measured by running the same `validate` the call path
117
+ * runs (`executeTool(spec, params.arguments ?? {}, …)`), not by reading `required` off the
118
+ * advertised JSON Schema. Those two are not the same question: `gp_attach` publishes
119
+ * `oneOf: [{required:[bundleId]}, {required:[pid]}]` with no top-level `required` key, so the
120
+ * schema read called it "takes nothing" while its own refinement refuses `{}` — and measured
121
+ * on the delivered artifact, the remedy this sentence prints sent the agent to a call answered
122
+ * `GP_E_BAD_PARAMS: attach takes exactly one of bundleId or pid`. An example the caller is
123
+ * guaranteed to fail is worse than no example, which is the rule `publishedNamesNear` below
124
+ * already states for the *name* half of the same sentence.
125
+ * `test/dispatch.test.mjs` checks every name in this sentence against `tools/list`, checks it
126
+ * again on a server deliberately built with a one-tool list, and now checks that the named
127
+ * tool really answers `arguments: {}` without a params refusal.
102
128
  */
103
129
  private callShapeRemedy;
130
+ /**
131
+ * Caller-authored text that rides a protocol error frame: bounded in length, neutralised
132
+ * for terminal control. The same product escapes a daemon-authored id with
133
+ * `renderForeign` and a report body with `escapeTerminalControl`, because an ESC can move
134
+ * the cursor and overwrite what the frame just said. Protocol-level text arrives from
135
+ * whoever wrote the frame — an MCP client, or anything that can reach the HTTP body — so
136
+ * the same rule applies before it is echoed back inside `Unknown tool: …`. Without a
137
+ * length bound, a 4 MB `params.name` is copied verbatim into the stdout frame, and one
138
+ * frame on a shared stdout is not a place to park whatever the caller typed.
139
+ */
140
+ private echoForeign;
104
141
  /**
105
142
  * The names this server actually answers with, nearest the caller's guess first. Every
106
143
  * name offered here is one `tools/list` just advertised: a suggestion the caller cannot
@@ -1,3 +1,4 @@
1
+ import fs from "node:fs";
1
2
  import { Duplex } from "node:stream";
2
3
  import { LineIo } from "./io.js";
3
4
  /**
@@ -19,6 +20,8 @@ import { LineIo } from "./io.js";
19
20
  export declare function daemonUnreachableRemedy(): string;
20
21
  /** Env override for the daemon socket path (default below). */
21
22
  export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
23
+ /** The launchd job this product installs — remedies name it so an agent can read the running job. */
24
+ export declare const LAUNCHD_JOB_LABEL = "com.glasspane.daemon";
22
25
  /**
23
26
  * Where this shell connects when nothing was named, in order: `GLASSPANE_ENGINE_SOCK`
24
27
  * (the env var {@link ENGINE_SOCKET_ENV} spells), then the explicit
@@ -83,6 +86,16 @@ export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
83
86
  * choose (`index.ts`, `http-gateway-cli.ts`).
84
87
  */
85
88
  export declare function defaultSocketPath(): string;
89
+ /**
90
+ * The socket the engine binds when *nothing* names one — the home default, read straight from
91
+ * the passwd-independent `os.homedir()` guess the daemon falls back to.
92
+ *
93
+ * Separate from `defaultSocketPath()` because a remedy that says "the default is X" must name
94
+ * the default even while `GLASSPANE_ENGINE_SOCK` is set to something else: echoing the override
95
+ * back as the default would tell the reader its own mistake is the engine's behaviour. This is
96
+ * also the one place `$HOME` is spelled for the socket, which `engine-client.test.mjs` counts.
97
+ */
98
+ export declare function homeDefaultSocketPath(): string;
86
99
  /**
87
100
  * The env override that actually names a socket, or `null` when it names nothing.
88
101
  *
@@ -115,6 +128,46 @@ export declare function socketOverride(value: string | undefined): string | null
115
128
  * is the ENOENT this shell already reports, not a usage error invented here.
116
129
  */
117
130
  export declare function refuseEmptySocketPath(value: string, flag: string): void;
131
+ /**
132
+ * The stat facts {@link trustSocket} needs, as a type so a test can hand it a real
133
+ * socket it made unreachable-by-permission without needing a second account.
134
+ */
135
+ export type SocketEvidence = Pick<fs.Stats, "uid" | "mode" | "isSocket">;
136
+ /**
137
+ * May this path carry the engine's word? `null` means yes; anything else is a
138
+ * three-field refusal to be handed to the caller before a single byte is written.
139
+ *
140
+ * Why this exists at all: the engine socket is owner-only (`chmod 0600`) and carries **no peer
141
+ * authentication** (SECURITY.md — same uid = full authority), so the socket *path* is what makes
142
+ * a reply mean anything. `GLASSPANE_ENGINE_SOCK` therefore is a trust root, not just a location:
143
+ * whatever this function lets through is a thing whose answers this shell renders as the engine's
144
+ * verified word, evidence pack included. Four facts disqualify a path:
145
+ * - the runtime cannot say which account it is running as, so ownership is unaskable;
146
+ * - the leaf is not a socket — a plain file planted there must be named as such instead of
147
+ * producing a connect error that reads like "the daemon is down";
148
+ * - the leaf or the directory holding it belongs to another uid, so this account did not place
149
+ * it there;
150
+ * - either carries a **write** bit for group or other. Write is the bit that matters: on a
151
+ * socket it grants the ability to send, on a directory the ability to create or replace the
152
+ * entry. Execute-only for others (`0755` — which is what a listener created by node itself
153
+ * carries before any chmod, measured on this machine) lets a reader look, not talk, so the
154
+ * daemon's own socket passes. A listener granting `0666` is advertising itself to the machine.
155
+ *
156
+ * `ENOENT` deliberately returns `null`: no file at the path is the daemon-not-running case, which
157
+ * the transport already renders as `GP_E_ENGINE_UNREACHABLE` with the restart command. Turning it
158
+ * into a trust refusal here would rename a known condition and break the remedy an agent is
159
+ * supposed to copy. A stat that fails for any **other** reason is a refusal, because "could not
160
+ * ask" is not evidence of trust.
161
+ *
162
+ * `read` and `euid` are seams, not abstractions: the other-account branches cannot be produced by
163
+ * an unprivileged test process, and a check whose only exercised path is the friendly one has not
164
+ * been checked. Everything else runs against a real socket on a real filesystem.
165
+ */
166
+ export declare function trustSocket(target: string, read?: (p: string) => SocketEvidence, euid?: number | null): {
167
+ code: string;
168
+ message: string;
169
+ remedy: string;
170
+ } | null;
118
171
  /** Fallback deadline for a method missing from the table below. */
119
172
  export declare const ENGINE_TIMEOUT_MS = 10000;
120
173
  /**
@@ -325,7 +378,26 @@ export declare function livenessProbeDecision(outcome: LivenessProbeOutcome): st
325
378
  * the state it really has (R8b-高3).
326
379
  */
327
380
  export type ShellSurface = "mcp" | "http";
328
- /** Where the answer to a timed-out request can be found, per surface. */
381
+ /**
382
+ * Where the answer to a timed-out request can be found, per surface.
383
+ *
384
+ * The HTTP arm is written against the line the gateway actually prints, because
385
+ * an exit a caller cannot walk is not an exit: it used to promise the reply "is
386
+ * written to this gateway's stderr **with its body**, so the operationId it
387
+ * carries can be read off that line". The real sink refuses exactly that — the
388
+ * body of a late reply is on-screen accessibility content, and `http-gateway.ts`
389
+ * hands it to `lateReplyBodyNote`, which writes a byte count plus a SHA-256
390
+ * digest and says in words that the text is not written (review 2026-10-09
391
+ * finding 3, F3 on 2026-10-27). So the sentence pointed a caller at bytes the
392
+ * product has decided do not exist on that path, and the id it told the caller
393
+ * to read is printed only when the reply's `operationId` matches the archive
394
+ * grammar. The wording below transcribes what the line really says; flipping the
395
+ * other way — making the note write the body — would break the trust boundary
396
+ * that keeps screen content out of a log file whose mode this product never
397
+ * sets, so it is not the fix. `test/daily-20261031-late-reply-route-shape.test.mjs`
398
+ * compares this sentence with a line the real gateway wrote, rather than testing
399
+ * each of them alone.
400
+ */
329
401
  export declare function lateReplyRoute(surface: ShellSurface): string;
330
402
  /**
331
403
  * 背压闸的出路。两条禁令各由一条现场证据撑着:探针本身也要过一次 `call()`,会被
@@ -440,8 +512,12 @@ export declare class EngineJsonRpcClient {
440
512
  expectedDaemonMethods?: readonly string[]);
441
513
  /**
442
514
  * The state root the daemon named in its own `hello` (additive since 1.15.0), or null
443
- * when no handshake answered that key. `null` means "this daemon does not report it" —
444
- * never "therefore it is the home default"; callers say which of the two they used.
515
+ * when no handshake *on the connection this transport currently holds* answered that key.
516
+ * `null` means "this daemon does not report it" — never "therefore it is the home
517
+ * default", and never "therefore it is what the daemon before this one said"; the field is
518
+ * cleared when a connection opens, which is the only way a reconnecting transport can
519
+ * answer "not measured" about a producer it has just replaced. Callers say which of the
520
+ * two they used.
445
521
  */
446
522
  private helloStateRoot;
447
523
  get reportedStateRoot(): string | null;
@@ -634,6 +710,12 @@ export declare function unixSocketEngineClient(socketPath: string, options?: {
634
710
  surface?: ShellSurface;
635
711
  /** Daemon methods this shell forwards; see {@link EngineJsonRpcClient}'s last parameter. */
636
712
  expectedDaemonMethods?: readonly string[];
713
+ /** Seam for {@link trustSocket}; production callers never pass it — the real stat is the default. */
714
+ trust?: (target: string) => {
715
+ code: string;
716
+ message: string;
717
+ remedy: string;
718
+ } | null;
637
719
  }): EngineJsonRpcClient;
638
720
  /**
639
721
  * Build a client over an existing LineIo (used by tests with a fake
package/dist/errors.d.ts CHANGED
@@ -103,6 +103,24 @@ export declare const GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
103
103
  * 而不是 4xx。
104
104
  */
105
105
  export declare const GP_E_STATE_ROOT_REFUSED = "GP_E_STATE_ROOT_REFUSED";
106
+ /**
107
+ * Shell-only: the socket this shell is about to write into is not one it can call the
108
+ * engine's. The engine socket is `chmod 0600` with **no peer authentication** (SECURITY.md:
109
+ * same uid = full authority), so the path is a trust root, not just a location: a leaf another
110
+ * account created, a leaf any other account may write to, or a directory any other account may
111
+ * replace the entry in all mean the bytes this shell reads back are not evidence of what the
112
+ * engine said — and every verdict this product publishes is built from those bytes.
113
+ *
114
+ * The judgement is made before the first byte leaves this process, so a refusal carries no
115
+ * claim that anything was executed. It deliberately does NOT reuse `GP_E_ENGINE_UNREACHABLE`:
116
+ * that code's remedy names a daemon restart, and restarting a service that is mid-`act` on the
117
+ * user's screen is an action this measurement does not license — the thing listening there may
118
+ * be running perfectly well, just not as the engine.
119
+ *
120
+ * It is also not in `SHELL_REQUEST_REFUSAL_CODES` below: this is not the caller's argument, so
121
+ * the HTTP surface answers it as 503 like the other infrastructure codes.
122
+ */
123
+ export declare const GP_E_SOCKET_TRUST = "GP_E_SOCKET_TRUST";
106
124
  /**
107
125
  * Shell-only: a declared review dimension is malformed. The daemon has no dimension
108
126
  * vocabulary at all — a dimension is the harness's annotation on a call, never an engine