glasspane-mcp 1.3.0 → 1.4.0

package/dist/audit-session.d.ts

@@ -33,6 +33,44 @@ export interface LateArrivalOutcome {
     /** The trail generation in force at the moment of the decision. */
     generationAtWrite: number;
 }
+/**
+ * How an id got into this trail, per id, in the words a renderer can put beside
+ * it. The three values are not adjectives of confidence: they name which
+ * mechanism wrote the id, and each one is a fact the session itself observes.
+ *
+ * - `in-order`: written by a call whose own request held a trail turn, answered
+ *   by a frame that echoed that request's id. This is the only entry the trail
+ *   may describe as verified.
+ * - `late`: written from a reply that landed after its caller had already been
+ *   answered, so it had no turn left to write at and took the position
+ *   {@link recordLateArrival} gives it — behind whatever is still outstanding.
+ *   The *operation* is the daemon's own; only its place in request order is
+ *   arranged by arrival.
+ * - `late-inferred`: that same late write, for a frame that echoed **no request
+ *   id** (R10-中2). Which request it answers is then a guess from the daemon's
+ *   in-order scheduling, not a match, and an id pulled out of it can be filed
+ *   under the wrong operation. The trail still records it — dropping it would
+ *   claim "no such operation ran", which is the more dangerous lie for an agent
+ *   deciding whether to click again — but it must not read as verified, and
+ *   `gp_recent_reports` has to say so from here rather than from the log line.
+ *
+ * Producers: `EngineJsonRpcClient`'s `LateReply.attribution` decides between the
+ * last two (`echoed-id` -> `late`, `arrival-order` -> `late-inferred`); a caller
+ * that passes nothing gets `late`, which is everything this session can see on
+ * its own.
+ */
+export type TrailProvenance = "in-order" | "late" | "late-inferred";
+/**
+ * The attribution a late arrival carries: the same two literals
+ * `engine-client.ts`'s `FrameAttribution` produces, and `unknown` for a caller
+ * that cannot say (a wiring that has not read the field yet).
+ */
+export type LateArrivalAttribution = "echoed-id" | "arrival-order" | "unknown";
+/**
+ * The sentence the surface that shows the trail puts beside one id. Written here
+ * because this is the layer that knows the mechanism; the tool layer renders it.
+ */
+export declare const TRAIL_PROVENANCE_NOTES: Readonly<Record<TrailProvenance, string>>;
 export declare class EvidenceAuditSession {
     private ids;
     private epoch;
@@ -46,8 +84,44 @@ export declare class EvidenceAuditSession {
      * order the turn machinery exists to remove.
      */
     private openGates;
-    /** Record every operationId/evidenceId found in an engine result frame. */
+    /**
+     * How each id in {@link ids} got here. Keyed by the id, because that is what a
+     * reader holds; the map is trimmed with the list and cleared when the trail
+     * restarts, so an id can never outlive the provenance that describes it.
+     */
+    private readonly provenance;
+    /**
+     * Non-null while {@link recordLateArrival} holds the trail, and says how the
+     * frame being written was attributed. This is what lets a plain
+     * `trail.record(result)` inside that callback be filed as a late arrival without
+     * the caller having to remember to say so: the write happens inside a window only
+     * that method opens, so the mechanism is visible here rather than being a claim
+     * somebody must repeat at every call site.
+     */
+    private lateWindow;
+    /**
+     * Record every operationId/evidenceId found in an engine result frame, tagged
+     * with the provenance of the path that is recording it (see
+     * {@link TrailProvenance}): `in-order` from a call that held its own trail turn,
+     * `late`/`late-inferred` from inside {@link recordLateArrival}.
+     */
     record(result: unknown): void;
+    /**
+     * How one id in this trail got recorded, or null when the trail does not hold
+     * it — never recorded, evicted past {@link AUDIT_HISTORY_LIMIT}, or cleared by a
+     * {@link restart}. A reader that lists ids for an agent renders
+     * {@link TRAIL_PROVENANCE_NOTES} for anything that is not `in-order`: an id
+     * pulled from a frame this shell only *guessed* an owner for must not appear
+     * beside one it matched by id (R10-中2).
+     *
+     * Read off the map alone, so the map *is* the record of what the trail holds: an
+     * id whose provenance outlives its own entry would come back labelled as if it
+     * were still listed, and the eviction and the restart are the two places that
+     * would have to remember to delete. `test/engine-client.test.mjs` pins both.
+     */
+    provenanceOf(id: string): TrailProvenance | null;
+    /** The ids currently filed as inferred; see {@link TrailProvenance}. */
+    inferredIds(): string[];
     /**
      * The trail's generation number. Every {@link restart} bumps it.
      *
@@ -109,8 +183,17 @@ export declare class EvidenceAuditSession {
      * decides whether that is acceptable; this method refuses it by default, because
      * "we do not know which attach this belongs to" is not a reason to write into
      * somebody else's trail.
+     *
+     * `attribution` is how the transport matched that frame to a request, and it is
+     * the difference between `late` and `late-inferred` below: a frame that echoed
+     * the id the client sent is confirmed, one with no id is filed against the
+     * oldest tracked request by the daemon's in-order scheduling (R10-中2). Anything
+     * this method writes is a late arrival by construction, so the window opens
+     * whether or not the caller can say more — the default `unknown` is what the
+     * session can see on its own, and it is *not* `in-order`: an unconfirmed
+     * attribution must not read as a verified one.
      */
-    recordLateArrival(apply: (session: EvidenceAuditSession) => void, admittedUnderGeneration?: number): Promise<LateArrivalOutcome>;
+    recordLateArrival(apply: (session: EvidenceAuditSession) => void, admittedUnderGeneration?: number, attribution?: LateArrivalAttribution): Promise<LateArrivalOutcome>;
     /**
      * 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

package/dist/dispatch.d.ts

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

package/dist/engine-client.d.ts

@@ -76,8 +76,10 @@ export declare const ENGINE_TIMEOUT_MS = 10000;
  * `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.
+ * answering early — the only thing that ends that registration is the transport
+ * going away, and `teardown` logs the tracked requests it drops when it does —
+ * 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;
 /**
@@ -126,6 +128,39 @@ export declare const ENGINE_DEADLINES_MS: {
 };
 /** Fixed part of an ffwd restore deadline (per-step cost is `act` above). */
 export declare const RESTORE_BASE_DEADLINE_MS = 30000;
+/**
+ * The single answer to "will re-issuing this method perform a change the daemon may
+ * already have carried out?". Exported because two other layers have to ask it —
+ * `tools.ts` when it rewrites an oversized reply, `http-gateway.ts` when it answers
+ * a curl caller — and a membership list copied into each of them is how the advice
+ * for one tool drifts back into "just retry the click". A caller that wants the
+ * *reason* per method owns that text; membership comes from here.
+ */
+export declare function isReplayUnsafeMethod(method: string): boolean;
+/** The non-replayable methods, for gates that must see the set change on purpose. */
+export declare const REPLAY_UNSAFE_METHOD_NAMES: readonly string[];
+/**
+ * Methods whose re-issue writes daemon state the *caller* depends on, even though
+ * replaying them is not unsafe in the sense {@link REPLAY_UNSAFE_REASONS} means
+ * (no operation of the user's is performed a second time). They are the other half
+ * of the answer to "may this be narrowed by sending it again?", and they are kept
+ * apart from the set above because `test/probe-liveness.test.mjs` pins that set's
+ * membership as the no-replay judgement.
+ *
+ * `snapshot` is here because of a ring, not of a click: `storeSnapshot`
+ * (`engine/Sources/GlassPaneEngine/EngineCore.swift:2070`) appends the new
+ * baseline and then trims oldest-first to `EngineCore.snapshotHistoryLimit` (the
+ * same file, line 25 — 8 entries). A `gp_snapshot` whose caller timed out may
+ * therefore have been carried out already, and every re-send — "with a smaller
+ * maxDepth", which is what the tool layer used to say — adds another entry that can
+ * evict the baseline the caller's *own earlier* snapshot returned, the one
+ * `gp_restore {snapshotId}` needs later. Evicting a caller's evidence to fetch a
+ * cheaper copy of it is not narrowing.
+ *
+ * `attach` writes state too, and is already a replay-unsafe method; `tools.ts`
+ * unions the two lists rather than repeating names here.
+ */
+export declare const STATE_CHANGING_ON_RETRY_METHOD_NAMES: readonly string[];
 /** Deadline for one request; `restore` scales with its replayed step count. */
 export declare function engineDeadlineMs(method: string, params?: Record<string, unknown>): number;
 /** When the caller gets its answer for `method`: its deadline, capped. */
@@ -209,15 +244,42 @@ export type ShellSurface = "mcp" | "http";
 export declare function lateReplyRoute(surface: ShellSurface): string;
 /**
  * Remedy for a deadline overrun: wait and measure, never restart on a probe that
- * merely went unanswered, and never replay a user-visible action.
+ * merely went unanswered, and never replay a request whose re-issue has a side
+ * effect.
  */
 export declare function slowEngineRemedy(method: string, surface?: ShellSurface): string;
+/** Log ceiling for a frame body; excess is marked, never silently cut. */
+export declare const LOG_BODY_CHARS: number;
+/**
+ * How a reply frame was matched to the request it is reported for.
+ *
+ * `echoed-id` is the frame carrying the request id this client sent and the
+ * lookup hitting; that is the only attribution this transport can *confirm*.
+ * `arrival-order` is the daemon's id-less answer (it loses the id on the paths
+ * that could not parse or could not serialize the frame), matched to the oldest
+ * request still tracked because the daemon answers in the order it received
+ * them — an inference from scheduling, never a confirmation, so anything written
+ * from it into an evidence trail has to carry that caveat with it
+ * (`EvidenceAuditSession.provenanceOf`).
+ *
+ * Spelled as the same two literals `audit-session.ts` accepts for the same
+ * reason: the transport is the only thing that sees the frame, and the session is
+ * the only thing that decides what the trail claims about an id.
+ */
+export type FrameAttribution = "echoed-id" | "arrival-order";
 /** One late engine reply, as handed to {@link EngineJsonRpcClient.onLateReply}. */
 export interface LateReply {
     method: string;
     result: unknown;
     /** Whatever `call()` was given; see {@link Pending.correlation}. */
     correlation?: number;
+    /**
+     * Whether this reply's *request* was confirmed by an echoed id or inferred
+     * from arrival order; see {@link FrameAttribution}. A sink that records this
+     * body into a trail must not present an `arrival-order` frame as a confirmed
+     * one, because the method it is filed under is a guess.
+     */
+    attribution: FrameAttribution;
 }
 /**
  * Request/response association over a line transport. Kept independent of
@@ -237,11 +299,27 @@ export declare class EngineJsonRpcClient {
     private readonly callerCeilingMs;
     /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
     private readonly surface;
-    private nextId;
-    private closed;
+    /**
+     * Every mutable piece of this client's state, in one object that is *never*
+     * reassigned through `this`.
+     *
+     * That is not a style choice (R10-中4). `tools.ts` hands one tool an engine view
+     * built with `Object.create(engine)`, which puts the real client on the shadow's
+     * prototype chain so the shadow shares its map, its sinks and its transport — and
+     * any method that runs with the *shadow* as `this` then writes its field on the
+     * shadow, because assigning a property that exists only on the prototype creates
+     * an own property instead of touching the prototype's. `pending` survived that
+     * only because it is a `Map` that gets mutated rather than reassigned. A
+     * `this.closed = true` did not: it marked the shadow closed and left the client
+     * sending requests on a transport it had been told to end. Reading state out of
+     * this box still resolves through the chain, and writing a property of it mutates
+     * the one box the client itself holds.
+     *
+     * `test/engine-client.test.mjs` closes the *shadow* and asserts the client behind
+     * it is closed, which is the observable form of the whole rule.
+     */
+    private readonly state;
     private readonly pending;
-    private noteHandler;
-    private lateReplyHandler;
     constructor(io: LineIo, timeoutMs?: number | undefined, identity?: EngineIdentityExpectation | null, 
     /**
      * Ceiling on the caller's wait (B-02). Injectable because a test cannot
@@ -271,6 +349,13 @@ export declare class EngineJsonRpcClient {
      * the eviction note says when something fell outside it.
      */
     onLateReply(handler: (reply: LateReply) => void): void;
+    /**
+     * Whether {@link close} has ended this client. Public because the answer has to
+     * be readable *through* the `Object.create` shadow the tool layer builds: a
+     * shadow that was closed has to report the client behind it closed, otherwise
+     * "closed" is a property of whichever object happened to receive the call.
+     */
+    isClosed(): boolean;
     /**
      * Send a request and await its matching response frame. `correlation` is
      * echoed to {@link onLateReply} if this request is answered after its caller
@@ -293,14 +378,37 @@ export declare class EngineJsonRpcClient {
     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.
+     * the retained head when the daemon echoed an id, else by arrival order, which
+     * is the oldest *tracked* request for the same reason the id-less frame path
+     * uses it (R9-高1) — and fail that one call only.
      */
     private failOversizedReply;
     private engineError;
-    /** Oldest request the caller is still waiting on (daemon FIFO order). */
-    private oldestOpen;
+    /**
+     * Oldest request this client still tracks, settled ones included: that is the
+     * request the daemon's arrival-ordered answer belongs to. `Map` iteration is
+     * insertion order, which is the order the requests went out.
+     *
+     * An entry whose id-less answer has already been taken (`arrivalOrderConsumed`)
+     * is passed over for *this* purpose while staying in the map for the echoed-id
+     * lookup: the guess has been spent once and may not be spent again on the next
+     * id-less frame, and the request it was spent on is still the request whose real
+     * reply can arrive with its id (finding 中-4).
+     */
+    private oldestTracked;
+    /**
+     * Route the reply that lands after its caller was already answered. `inferred`
+     * marks an attribution made by arrival order rather than by a matching id, and
+     * says so in the note — and hands the same distinction to the sink, which is
+     * the only place the caveat can travel with the body it records (R10-中2: an
+     * id-less result is a *guess about which request this is the answer to*, and a
+     * trail that files it without that note presents a guessed frame as a verified
+     * one). What the transport may not do is claim the sink recorded anything: it
+     * cannot see whether the trail accepted the frame or refused it for belonging to
+     * a superseded attach.
+     */
     private reportLateReply;
+    private reportSinkFailure;
     private resolve;
     private reject;
     /**
@@ -309,7 +417,17 @@ export declare class EngineJsonRpcClient {
      * longer answer it, and keep it after a timeout for the late reply.
      */
     private complete;
-    /** Reject everything outstanding and drop every handle. */
+    /**
+     * Reject everything outstanding and drop every handle. The settled entries go
+     * too, and that has to be reported: each of them was answered with "the
+     * request stays registered" (`onDeadline`) and with {@link lateReplyRoute}'s
+     * promise that its reply is attributed when it lands. This map is what that
+     * promise was standing on, so clearing it silently leaves an agent reading the
+     * log for an operation that really ran, finding nothing, and unable to tell
+     * "this shell stopped tracking it" from "it never happened" — the difference
+     * that decides whether it re-performs an `act` on the user's screen (R9-中1).
+     * The reverse mutation is to delete this note and keep the silent clear.
+     */
     private teardown;
     private report;
     /**
@@ -321,6 +439,7 @@ export declare class EngineJsonRpcClient {
     private handshake;
     private verifyIdentity;
 }
+export declare function truncate(text: string): string;
 /** How a transport stream is opened; injectable so tests need no socket. */
 export type EngineTransportOpener = (socketPath: string) => Duplex;
 /**