glasspane-mcp 0.1.0 → 1.1.1

package/README.md

@@ -3,7 +3,19 @@
 GlassPane 的 MCP 服务器（stdio）：把 AI 客户端的 `gp_*` 工具调用转发给本机
 GlassPane 后台服务，并把每一次界面操作的证据带回给你。
 
-## 用法
+This package is the **transport layer only**. It needs the GlassPane daemon
+(`glasspaned`) running on this Mac, which the installer provides — installing this
+package alone does not give you a working verification engine.
+
+本包只是转发层：它需要本机已在跑 GlassPane 后台服务，而该服务由安装器产出。
+只装本包不会得到可用的验证引擎——先装引擎：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh | sh
+# 或：npx glasspane-install
+```
+
+## 用法 / Usage
 
 ```bash
 npm i -g glasspane-mcp
@@ -21,4 +33,11 @@ MCP 客户端配置：
 按错误里的命令执行即可，无需查阅其它文档。
 
 工具清单与语义以 `gp_*` 运行时 `tools/list` 返回为准。
+
+## What ships in this package / 包里有什么
+
+`dist/index.js` 是 esbuild 单文件产物：`@iterate/kernel`（schema 真源）在发布时
+已捆绑内联，包内不存在指向源码仓库的 `file:` 依赖；`schemas/` 是 kernel schema
+的发布副本，每次 `npm run bundle` 重新同步。
+
 License: MIT.

package/dist/audit-session.d.ts

@@ -10,13 +10,49 @@
  * and simply restarts the trail). Does not persist across process restarts.
  */
 export declare const AUDIT_HISTORY_LIMIT = 20;
+/**
+ * One position in a session's trail *request order*, handed out by
+ * {@link EvidenceAuditSession.claimTrailTurn}. `release` is idempotent.
+ */
+export interface TrailTurn {
+    /** Wait until every turn claimed before this one has released. */
+    acquire(): Promise<void>;
+    /** Hand the trail on: this turn is done with it, or never will be. */
+    release(): void;
+}
 export declare class EvidenceAuditSession {
     private ids;
+    /**
+     * Turns claimed but not released. This, not a "latest gate", is what a new
+     * claim waits for: a turn that abandons the trail (its engine call failed
+     * before any mutation) releases *out of order*, and a chain that only looked
+     * at the immediately preceding turn would let everything behind it run while
+     * an older, still-outstanding act had not written yet — the exact completion
+     * order the turn machinery exists to remove.
+     */
+    private openGates;
     /** Record every operationId/evidenceId found in an engine result frame. */
     record(result: unknown): void;
-    /** Clear the trail (called after a successful attach). */
+    /**
+     * Clear the trail (called after a successful attach).
+     *
+     * Deliberately does *not* touch {@link openGates}: outstanding turns are not
+     * outstanding mutations, and forgetting them would let a later read overtake
+     * an act that is still going to write.
+     */
     reset(): void;
     /** The most recent `limit` recorded operationIds, oldest first. */
     recentIds(limit: number): string[];
+    /**
+     * Claim the next position in this session's trail request order, so that
+     * overlapping calls mutate and read `ids` in the order they were admitted
+     * rather than in the order the daemon answered.
+     *
+     * Synchronous on purpose — a claim made after an `await` would itself be
+     * ordered by completion. Callers hold a turn only across a `record()` /
+     * `reset()` / `recentIds()`, never across an engine round trip, so the queue
+     * can delay the moment a reply is built but never a request at the daemon.
+     */
+    claimTrailTurn(): TrailTurn;
 }
 //# sourceMappingURL=audit-session.d.ts.map

package/dist/dispatch.d.ts

@@ -2,11 +2,31 @@ import { EngineJsonRpcClient } from "./engine-client.js";
 import { ToolSpec } from "./tools.js";
 import { EvidenceAuditSession } from "./audit-session.js";
 export declare const JSONRPC: "2.0";
-/** MCP protocol version echoed on initialize (spec §6.1). */
+/**
+ * This shell's own MCP protocol version — the fallback answer on initialize
+ * when the client asks for a version we do not implement (spec §6.1).
+ */
 export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
+/**
+ * MCP revisions this shell genuinely interoperates with, i.e. the ones
+ * initialize echoes back. A version is listed only when everything the shell
+ * answers is part of that revision's own dialect: it implements
+ * `initialize`/`ping`/`tools/list`/`tools/call` over newline-delimited JSON-RPC
+ * 2.0 on stdio, advertises the `tools` capability alone with
+ * `listChanged: false`, sends no batch request and no notification it has not
+ * been asked for, and returns `content` text without `structuredContent`,
+ * `outputSchema`, sampling, roots, elicitation or streaming. All of that is
+ * inside the oldest revision below, so echoing it back promises nothing the
+ * shell cannot deliver (spec §6.1: 回显客户端版本，不识别时回落本常量).
+ *
+ * Anything newer or otherwise unknown falls back to {@link
+ * MCP_PROTOCOL_VERSION} — including a *newer* revision: this shell has not been
+ * shown against it, so it does not claim it.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
 export declare const SERVER_INFO: {
     readonly name: "glasspane-mcp";
-    readonly version: "0.1.0";
+    readonly version: "1.1.1";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;
@@ -38,6 +58,14 @@ export declare class McpServer {
     handleLine(line: string): Promise<RpcResponse | null>;
     private handleNotification;
     private dispatch;
+    /**
+     * Spec §6.1: echo the client's protocolVersion when this server implements it
+     * (the shipped {@link SUPPORTED_PROTOCOL_VERSIONS}; see that list for what
+     * "implements" means here), otherwise fall back to MCP_PROTOCOL_VERSION. A
+     * missing or non-string version is just "not recognized" — it falls back too,
+     * and never throws.
+     */
+    private negotiateProtocolVersion;
     private callTool;
     private asParams;
     private isRequestBody;

package/dist/engine-client.d.ts

@@ -1,3 +1,4 @@
+import { Duplex } from "node:stream";
 import { LineIo } from "./io.js";
 /**
  * Agent-actionable remedy for an unreachable daemon (P6 §11 audit items ④/⑥:
@@ -10,10 +11,82 @@ import { LineIo } from "./io.js";
 export declare function daemonUnreachableRemedy(): string;
 /** Env override for the daemon socket path (default below). */
 export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
-/** Connection/response timeout, per spec §6.2. */
-export declare const ENGINE_TIMEOUT_MS = 10000;
-/** The daemon listens here by default (spec §3.1). */
+/**
+ * The daemon listens here by default (spec §3.1). Single source: the CLI
+ * argument parser in index.ts and the reconnecting transport both resolve the
+ * path through this function, so an env override cannot be honoured on one side
+ * only.
+ */
 export declare function defaultSocketPath(): string;
+/** Fallback deadline for a method missing from the table below. */
+export declare const ENGINE_TIMEOUT_MS = 10000;
+/**
+ * Per-method wall-clock deadlines. 10 s is the daemon's *internal* latency
+ * flag (`EngineCore.performanceLatencyBudgetMs`), not its worst-case wall
+ * time: a tree walk gets 10 s of its own (`AXChannel.treeTimeoutSeconds`), an
+ * act reads the tree twice around a 2 s ping, and an ffwd restore replays up
+ * to 64 steps (ParamValidation.stepsUpper) by calling act per step. A uniform
+ * 10 s deadline diagnoses a slow-but-healthy daemon as "unreachable, restart
+ * it" and then throws away the reply that lands later, so every value here is
+ * strictly larger than the daemon's own worst case for that method.
+ *
+ * What these numbers do after B-02: they are still the caller's wait for every
+ * method below the ceiling, and above it they are the daemon-side worst case
+ * the timeout text quotes — the caller answered at the ceiling, while the
+ * request stays registered so the real reply is attributed when it lands.
+ */
+export declare const ENGINE_DEADLINES_MS: {
+    readonly hello: 15000;
+    readonly attach: 30000;
+    readonly act: 120000;
+    readonly observe: 45000;
+    readonly assert_element: 60000;
+    readonly diagnose: 30000;
+    readonly last_evidence: 60000;
+    readonly snapshot: 90000;
+    readonly probe_status: 15000;
+    readonly shutdown: 15000;
+};
+/** Fixed part of an ffwd restore deadline (per-step cost is `act` above). */
+export declare const RESTORE_BASE_DEADLINE_MS = 30000;
+/**
+ * B-02: how long a *caller* may be kept waiting for any method, whatever the
+ * daemon's own worst case is.
+ *
+ * A real MCP client times a single request out at around 60 s, stops waiting,
+ * and the agent — holding no answer, no code and no remedy — re-issues the
+ * call. On `act` that re-issue performs the same click on the user's screen a
+ * second time, which is precisely the harm a deadline is meant to remove. So
+ * the ceiling sits below a client's patience: the shell answers at 50 s with
+ * `GP_E_ENGINE_TIMEOUT` and the no-replay remedy, and the request stays
+ * registered, so the reply that arrives later is still attributed and written
+ * to the log (`onDeadline` -> `reportLateReply`). Nothing is discarded by
+ * answering early, which is what makes the multi-minute deadlines above safe to
+ * cap: they describe the daemon, not the caller's wait.
+ */
+export declare const CALLER_VISIBLE_CEILING_MS = 50000;
+/** When the caller gets its answer for `method`: its deadline, capped. */
+export declare function callerDeadlineMs(method: string, params?: Record<string, unknown>, ceilingMs?: number): number;
+/** Deadline for one request; `restore` scales with its replayed step count. */
+export declare function engineDeadlineMs(method: string, params?: Record<string, unknown>): number;
+/** Engine protocol version this shell speaks (daemon `hello.protocolVersion`). */
+export declare const ENGINE_PROTOCOL_VERSION = "0";
+/** Daemon self-report the shell compares a fresh connection against. */
+export interface EngineIdentityExpectation {
+    /**
+     * Engine release this shell was paired with: the repo keeps one version line,
+     * so a difference means the MCP config points at another build. Handed over
+     * by the entry point rather than minted here, because a literal in this file
+     * would sit outside the version-site guard.
+     */
+    version?: string;
+}
+/**
+ * Shell-side failure codes live in `errors.ts` with the rest of the agent-facing
+ * vocabulary (X-15); this file used to declare them locally, which left
+ * `GP_E_ENGINE_TIMEOUT` spelled in two places with only a comment keeping them
+ * together.
+ */
 /** Error frame returned by the daemon (spec §3.2.1) or raised by the shell. */
 export interface EngineErrorBody {
     code: string;
@@ -27,6 +100,8 @@ export declare class EngineCallError extends Error {
     constructor(code: string, message: string, remedy: string);
     toBody(): EngineErrorBody;
 }
+/** Remedy for a deadline overrun: wait and measure, never restart or replay. */
+export declare function slowEngineRemedy(method: string): string;
 /**
  * Request/response association over a line transport. Kept independent of
  * the transport so tests inject a fake LineIo (spec §7.1 "fake engine
@@ -34,18 +109,91 @@ export declare class EngineCallError extends Error {
  */
 export declare class EngineJsonRpcClient {
     private readonly io;
-    private readonly timeoutMs;
+    private readonly timeoutMs?;
+    private readonly identity;
+    /**
+     * Ceiling on the caller's wait (B-02). Injectable because a test cannot
+     * wait 50 s, and because the ceiling is a property of *who is asking* — a
+     * caller with a longer patience gets a longer wait, never a longer
+     * registration.
+     */
+    private readonly callerCeilingMs;
     private nextId;
+    private closed;
     private readonly pending;
-    constructor(io: LineIo, timeoutMs?: number);
+    private noteHandler;
+    constructor(io: LineIo, timeoutMs?: number | undefined, identity?: EngineIdentityExpectation | null, 
+    /**
+     * Ceiling on the caller's wait (B-02). Injectable because a test cannot
+     * wait 50 s, and because the ceiling is a property of *who is asking* — a
+     * caller with a longer patience gets a longer wait, never a longer
+     * registration.
+     */
+    callerCeilingMs?: number);
+    /**
+     * Sink for facts that cannot be attached to any request of the caller: a
+     * late reply, a frame with an id this client never issued, a daemon that
+     * fails its handshake. Without a sink these stay invisible, which is how
+     * "not measured" turns into a confident wrong story.
+     */
+    onEngineNote(handler: (note: string) => void): void;
     /** Send a request and await its matching response frame. */
     call(method: string, params?: Record<string, unknown>): Promise<unknown>;
     close(): void;
+    /**
+     * Timeout path: settle the caller with a *slow* diagnosis but keep the
+     * entry, so a reply landing afterwards is delivered instead of thrown away.
+     * Only the transport going away makes a request unrecoverable.
+     */
+    private onDeadline;
+    /**
+     * A settled-by-timeout entry is what makes a late reply attributable, so the
+     * retention is bounded oldest-first and the eviction is logged, not silent.
+     */
+    private retainForLateReply;
     private handleMessage;
-    private failAll;
+    private settleFromFrame;
+    /**
+     * A frame over the cap: attribute it to the request it belonged to — from
+     * the retained head when the daemon echoed an id, else by arrival order —
+     * and fail that one call only.
+     */
+    private failOversizedReply;
+    private engineError;
+    /** Oldest request the caller is still waiting on (daemon FIFO order). */
+    private oldestOpen;
+    private reportLateReply;
+    private resolve;
+    private reject;
+    /**
+     * Single settle funnel: clears the deadline timer on every path and marks
+     * the entry settled. Callers delete the entry when the transport can no
+     * longer answer it, and keep it after a timeout for the late reply.
+     */
+    private complete;
+    /** Reject everything outstanding and drop every handle. */
+    private teardown;
+    private report;
+    /**
+     * R4-06: both sides self-report protocol/version and the repo keeps a single
+     * version line, yet nothing compared them at runtime — an old daemon under a
+     * new shell only surfaced as a mystery schema error later. Handshake once
+     * per (re)connection and report the measurement, including "unmeasured".
+     */
+    private handshake;
+    private verifyIdentity;
 }
-/** Production client bound to a Unix socket path (lazy connect on first call). */
-export declare function unixSocketEngineClient(socketPath: string): EngineJsonRpcClient;
+/** How a transport stream is opened; injectable so tests need no socket. */
+export type EngineTransportOpener = (socketPath: string) => Duplex;
+/**
+ * Production client on a Unix socket: lazy connect, reconnect on demand once
+ * the daemon is back, re-handshake per connection.
+ */
+export declare function unixSocketEngineClient(socketPath: string, options?: {
+    identity?: EngineIdentityExpectation;
+    open?: EngineTransportOpener;
+    callerCeilingMs?: number;
+}): EngineJsonRpcClient;
 /**
  * Build a client over an existing LineIo (used by tests with a fake
  * transport and by non-socket connectivity).

package/dist/errors.d.ts

@@ -9,6 +9,17 @@ export declare const GP_E_NO_EVIDENCE = "GP_E_NO_EVIDENCE";
 export declare const GP_E_INTERNAL = "GP_E_INTERNAL";
 export declare const GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 export declare const GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
+/**
+ * Codes this shell raises for itself, in one place so a string literal cannot
+ * exist twice with different spellings (X-15). They are **not** daemon codes:
+ * the daemon's `GPErrorCode` enum has no counterpart for either, because both
+ * describe a failure of the shell↔engine connection rather than of a request —
+ * a deadline this process chose to stop waiting on, and a frame too large to
+ * put on the wire. An agent must be able to tell those apart from a daemon
+ * error, and the daemon's own vocabulary is the only place that could add them.
+ */
+export declare const GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
+export declare const GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
 export interface ToolErrorText {
     code: string;
     message: string;

package/dist/evidence-report.d.ts

@@ -1,11 +1,26 @@
 import type { EvidencePack } from "@iterate/kernel";
+/**
+ * What a report may be handed: a validated pack, or the same structure with
+ * `schemaVersion` widened so it can carry provenance text
+ * (`glasspane.evidence/0.1-draft (read as glasspane.evidence/0.1)`). Every
+ * `EvidencePack` is assignable here; only the renderer's own first line reads
+ * the widened field, so no consumer of the strict type sees this shape.
+ */
+export type EvidencePackReportView = Omit<EvidencePack, "schemaVersion"> & {
+    schemaVersion: string;
+};
 /**
  * Type-mirrored renderer of the engine's `EvidenceReportGenerator`
- * (engine/Sources/GlassPaneEngine/EvidenceReportGenerator.swift). Both
- * implementations share the same structural contract (same titles, sections,
- * summary lines, escaping and placeholder semantics) and are covered by the
- * same golden expectations (P1 spec v1.3 §12.1), so a change must be applied
- * to both files in the same commit to avoid drift.
+ * (engine/Sources/GlassPaneEngine/EvidenceReportGenerator.swift): same title,
+ * same summary-line order (attribution / breaker / assert / act / axEvent /
+ * handlerProbe / stateDiff / pixelDiff / responsiveness / crash), same
+ * escaping, same placeholder semantics (P1 spec v1.3 §10.2).
+ *
+ * The mirror is guarded by a shared golden, not by this comment:
+ * `kernel/fixtures/report.ok-01.md` / `.html` hold the byte-exact output for
+ * the pack both suites call `goldenPack()`. `test/evidence-report.test.mjs`
+ * compares this side, `EngineP1Batch4Tests` the engine side, so a one-sided
+ * change fails a golden (spec v1.3 §12 P1-D1, §13.5 同一 commit 双改).
  */
 export interface ReportSection {
     title: string;
@@ -15,16 +30,17 @@ export interface ReportSection {
 export declare const PLACEHOLDER = "\u2014";
 export declare const SECTION_TITLES: readonly ["PATH", "ANOMALY", "EVIDENCE", "NEXT"];
 /** `operationId · measure · level`, mirroring the engine's reportTitle. */
-export declare function reportTitle(pack: EvidencePack): string;
+export declare function reportTitle(pack: EvidencePackReportView): string;
 /** Attribution / contamination / circuit-breaker / signal summary lines. */
-export declare function evidenceSummaryLines(pack: EvidencePack): string[];
+export declare function evidenceSummaryLines(pack: EvidencePackReportView): string[];
 /** Compact Markdown view (terminal / dialog friendly). */
-export declare function renderMarkdown(pack: EvidencePack, diagnostics: string | undefined): string;
+export declare function renderMarkdown(pack: EvidencePackReportView, diagnostics: string | undefined): string;
 /** Full HTML view with an operationId anchor; all values escaped. */
-export declare function renderHTML(pack: EvidencePack, diagnostics: string | undefined): string;
+export declare function renderHTML(pack: EvidencePackReportView, diagnostics: string | undefined): string;
 /**
  * Escape HTML metacharacters in values that cross into a report (spec v1.3
- * §10.5, no injection). Shared so aggregation headers escape too.
+ * §13.4, the five-character escape set, no injection). Shared so aggregation
+ * headers escape too.
  */
 export declare function escapeHTML(value: string): string;
 //# sourceMappingURL=evidence-report.d.ts.map