@mcp-index/sdk 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ additive feature, patch = fix). Backward-compatible additions only in 0.2.0.
 
 ## [Unreleased]
 
+## 0.18.1 - 2026-10-13
+
+### Changed
+
+- A `tools/list` read through `requestStream`, on the session or on `experimental.tasks`, goes through the same listing filter as `listTools`. Before, a tool that `listTools` leaves out still came back that way.
+- With `scanResults`, a result that arrives through a stream is scanned like a `callTool` result: `requestStream` with `tools/call` on either seam, and `experimental.tasks.callToolStream`. So is a task's result read later through `request({method: "tasks/result"})`, `getTaskResult` or `experimental.tasks.getTaskResult`, under the name of the tool whose gated call created the task. Without `scanResults` nothing changes.
+
+## 0.18.0 - 2026-10-11
+
+### Security
+
+- Fixes GHSA-phh5-4p9f-4qmg (https://github.com/mcpindex-ai/mcpindex-sdk-ts/security/advisories/GHSA-phh5-4p9f-4qmg), cases where changed or new tool text reached the agent under guard and strict. Affected: @mcp-index/sdk < 0.18.0 and mcpindex-gate < 0.20.0.
+
+### Changed
+
+- The wrapper reads the server's `instructions` after connect, pins them beside the tool pins (`.<server>.context.json`, the same format the gate's proxy writes), and reports a first pin or a change through the new `onContextDrift` option and one stderr line. It never changes what `getInstructions()` returns. It needs a file pin store. A numbers-only change is reported; this SDK does not apply the gate's digit budget.
+- Under guard and strict a pinned tool that adds an outputSchema is left out once for review and its call holds when the schema carries any string or any name under properties, patternProperties, $defs or definitions. A property name counts, so expect one review per tool when a server starts returning structured output. A bare `{"type": "object"}` is still shown.
+- The first paginated list on an empty pin store pins every page. Before, page 2 was held as new tools on an already-pinned server. Only the list that opened on the empty store can do this, only while it is current, and only while every pin was written by it; a list_changed, any call, a newer list or the last page ends it.
+- A tool whose title is not a string is left out of the list as a wrong type, under guard and strict, and the title is never recorded. The field-set marker moves to 3; any marker from 2 up, including one from a newer version, counts as complete.
+- Pending records carry the field-set version. Approving one written by 0.16 leaves the pin to record its fields on the next list, so the tool is not held again right after approval; one written by 0.17 keeps its version.
+- A tool whose `annotations` key is present with the value `undefined` (an in-process McpServer tool registered without annotations) is shown. Before, it was left out as a wrong type.
+
 ## 0.17.0 - 2026-10-11
 
 ### Changed

package/README.md

@@ -75,8 +75,13 @@ The pin records every top-level field a server lists for a tool (`title`,
 `icons`, `_meta`, `execution`, and any later field) and annotation keys other
 than the four hints. A change to one of them on a pinned tool leaves the tool
 out under guard and strict. A pin written before 0.17.0 records those fields
-once, from the first matching list. First-time `outputSchema` text on an
-otherwise unchanged tool is still shown.
+once, from the first matching list. A first `outputSchema` is held the same way when it
+carries any string or property name, which covers most structured output: expect
+one review per tool when a server starts returning it.
+
+With a file pin store, the wrapper also reads the server's `instructions` after
+connect, pins them, and reports a first pin or a change through
+`onContextDrift`. `getInstructions()` still returns what the server sent.
 
 ## Sign in (optional) - `mcpindex login`
 

package/dist/src/ambient.d.ts

@@ -23,6 +23,10 @@
  *
  * HONEST VOICE. Never the words protected / secured / safe in any emitted line.
  */
+/** Sanitize a remote-server-controlled label (tool/server name) before it is rendered into a
+ * stderr line: drop ANSI escapes / CR / LF / other control bytes and bound the length. Defends
+ * the terminal and any downstream log parser against forged-line / escape-sequence injection. */
+export declare function safeLabel(value: unknown): string;
 /** Cadence. FIRST_TOUCH (default): one line per distinct tool, then silent + a session
  * summary. SUMMARY: no per-call lines, only the end-of-session footer. EVERY: a line on
  * every call (loud — opt-in only). OFF: nothing. */

package/dist/src/ambient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ambient.d.ts","sourceRoot":"","sources":["../../src/ambient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAwBH;;oDAEoD;AACpD,oBAAY,WAAW;IACrB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,GAAG,QAAQ;CACZ;AAED,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AASlD;;;;wFAIwF;AACxF,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAetD;AAED;6EAC6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;4CAE4C;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;AAE1D,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;yFAEyF;AACzF,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAqBzC,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAED;;wDAEwD;AACxD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,sBAA2B;IAMhD,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,eAAe;IAQpE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;gFAC4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAa/F;;6BAEyB;IACzB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,kBAAkB,GAAG,WAAW,GAAG,IAAI;IAmB3G;;2FAEuF;IACvF,cAAc,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,GAAG,IAAI;IAahF;oFACgF;IAChF,OAAO,CAAC,IAAI;CAmBb"}
+{"version":3,"file":"ambient.d.ts","sourceRoot":"","sources":["../../src/ambient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAgBH;;iGAEiG;AACjG,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGhD;AAED;;oDAEoD;AACpD,oBAAY,WAAW;IACrB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,GAAG,QAAQ;CACZ;AAED,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AASlD;;;;wFAIwF;AACxF,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAetD;AAED;6EAC6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;4CAE4C;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;AAE1D,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;yFAEyF;AACzF,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAqBzC,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAED;;wDAEwD;AACxD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,sBAA2B;IAMhD,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,eAAe;IAQpE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;gFAC4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAa/F;;6BAEyB;IACzB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,kBAAkB,GAAG,WAAW,GAAG,IAAI;IAmB3G;;2FAEuF;IACvF,cAAc,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,GAAG,IAAI;IAahF;oFACgF;IAChF,OAAO,CAAC,IAAI;CAmBb"}

package/dist/src/ambient.js

@@ -38,7 +38,7 @@ const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
 /** Sanitize a remote-server-controlled label (tool/server name) before it is rendered into a
  * stderr line: drop ANSI escapes / CR / LF / other control bytes and bound the length. Defends
  * the terminal and any downstream log parser against forged-line / escape-sequence injection. */
-function safeLabel(value) {
+export function safeLabel(value) {
     const text = typeof value === "string" ? value : String(value);
     return text.replace(CONTROL_CHARS, "").slice(0, MAX_LABEL);
 }

package/dist/src/ambient.js.map

@@ -1 +1 @@
-{"version":3,"file":"ambient.js","sourceRoot":"","sources":["../../src/ambient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ambient.js","sourceRoot":"","sources":["../../src/ambient.ts"],"names":[],"mappings":"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"}

package/dist/src/contextWatch.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The server's `instructions`, observed and pinned (port of Python
+ * `context_observe` / `context_pin`, observation only).
+ *
+ * MCP hosts put a server's `instructions` into the agent's context on connect.
+ * The tool hash does not cover them, so a server can keep every tool identical
+ * and rewrite the text the model reads first. The wrapper reads them after
+ * connect, pins them on first sight beside the tool pins, and reports a change.
+ * It never changes what `getInstructions()` returns: stripping the text removes
+ * the server's own guidance, replaying a pinned copy freezes first-connect text,
+ * and holding calls is a denial of service whoever controls the text can aim.
+ *
+ * The file is the same format the Python store writes
+ * (`.<stem>.context.json`, schema_version 1, a map of server id to pin), so a
+ * proxy and a wrapper on one server share a baseline. Limits against Python: no
+ * digit-budget carve-out (a numbers-only change is reported as
+ * `numeric-unbounded`), and the store is not recorded in the ever-pinned index,
+ * so a deleted TS-written store reads as a first run.
+ */
+export type ContextOutcome = "pinned" | "unchanged" | "numeric-unbounded" | "drifted" | "cosmetic" | "unobserved" | "tainted" | "skewed";
+export interface ContextObservation {
+    readonly outcome: ContextOutcome;
+    readonly serverId: string;
+    readonly kinds: readonly string[];
+    readonly safetyRelevant: boolean;
+    readonly detail: string;
+}
+interface Leg {
+    status: string;
+    text: string | null;
+    text_dropped: boolean;
+    hash: string | null;
+    len: number | null;
+}
+interface ContextPinJson {
+    server_id: string;
+    pinned_at: string;
+    via: string;
+    protocol_version: string | null;
+    observed_via: string | null;
+    legs: Record<string, Leg>;
+    observed: Record<string, Leg>;
+    observed_at: string | null;
+}
+/** `.<stem>.context.json` beside the tool pin file (Python `default_context_store_path`). */
+export declare function defaultContextStorePath(pinStorePath: string): string;
+/** The instructions leg as Python `_instructions_from` shapes it: the hash is over
+ * the full UTF-8 text, the length counts code points, and text over the cap is
+ * dropped, never truncated. */
+export declare function legFromInstructions(raw: unknown): Leg;
+/** Classify one observation against the pin (Python `observe`). Pure. */
+export declare function classifyInstructions(pinned: ContextPinJson | null, observed: Leg, serverId: string, observedVia: string, storeTainted: boolean): ContextObservation;
+/** Owns one server's context pin and turns observations into reports. */
+export declare class ContextWatcher {
+    private readonly serverId;
+    private readonly onEvent;
+    private readonly now;
+    private readonly store;
+    private storeError;
+    constructor(path: string, serverId: string, onEvent: (obs: ContextObservation) => void, now: () => string);
+    get path(): string | null;
+    observe(instructions: unknown, observedVia: string, protocolVersion: string | null): ContextObservation;
+    private emit;
+}
+export {};
+//# sourceMappingURL=contextWatch.d.ts.map

package/dist/src/contextWatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextWatch.d.ts","sourceRoot":"","sources":["../../src/contextWatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAwBH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,mBAAmB,GACnB,SAAS,GACT,UAAU,GACV,YAAY,GACZ,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,GAAG;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIpE;AAiBD;;+BAE+B;AAC/B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAQrD;AAsJD,yEAAyE;AACzE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,GAAG,IAAI,EAC7B,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,OAAO,GACpB,kBAAkB,CAyBpB;AAED,yEAAyE;AACzE,qBAAa,cAAc;IAMvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,UAAU,CAAuB;gBAGvC,IAAI,EAAE,MAAM,EACK,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,EAC1C,GAAG,EAAE,MAAM,MAAM;IAWpC,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAExB;IAED,OAAO,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,kBAAkB;IAsCvG,OAAO,CAAC,IAAI;CAQb"}

package/dist/src/contextWatch.js

@@ -0,0 +1,328 @@
+/**
+ * The server's `instructions`, observed and pinned (port of Python
+ * `context_observe` / `context_pin`, observation only).
+ *
+ * MCP hosts put a server's `instructions` into the agent's context on connect.
+ * The tool hash does not cover them, so a server can keep every tool identical
+ * and rewrite the text the model reads first. The wrapper reads them after
+ * connect, pins them on first sight beside the tool pins, and reports a change.
+ * It never changes what `getInstructions()` returns: stripping the text removes
+ * the server's own guidance, replaying a pinned copy freezes first-connect text,
+ * and holding calls is a denial of service whoever controls the text can aim.
+ *
+ * The file is the same format the Python store writes
+ * (`.<stem>.context.json`, schema_version 1, a map of server id to pin), so a
+ * proxy and a wrapper on one server share a baseline. Limits against Python: no
+ * digit-budget carve-out (a numbers-only change is reported as
+ * `numeric-unbounded`), and the store is not recorded in the ever-pinned index,
+ * so a deleted TS-written store reads as a first run.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { ChangeKind, isNumericOnlyDescriptionChange } from "./schemaDiff.js";
+const CONTEXT_STORE_VERSION = 1;
+const MAX_INSTRUCTIONS_CHARS = 16_384;
+const LEG = "instructions";
+const SAFETY_KINDS = new Set([ChangeKind.INSTRUCTIONS_ADDED, ChangeKind.INSTRUCTIONS_CHANGED]);
+/** `.<stem>.context.json` beside the tool pin file (Python `default_context_store_path`). */
+export function defaultContextStorePath(pinStorePath) {
+    let stem = basename(pinStorePath);
+    if (stem.endsWith(".json"))
+        stem = stem.slice(0, -".json".length);
+    return join(dirname(pinStorePath) || ".", `.${stem}.context.json`);
+}
+/** Code points in `s` without building an array: a spread of a very long string can
+ * exhaust the heap, which no try/catch survives. */
+function codePointLength(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff)
+                i++;
+        }
+        n++;
+    }
+    return n;
+}
+/** The instructions leg as Python `_instructions_from` shapes it: the hash is over
+ * the full UTF-8 text, the length counts code points, and text over the cap is
+ * dropped, never truncated. */
+export function legFromInstructions(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        return { status: "ok", text: null, text_dropped: false, hash: null, len: null };
+    }
+    const len = codePointLength(raw);
+    const hash = "sha256:" + createHash("sha256").update(Buffer.from(raw, "utf8")).digest("hex");
+    const text = len <= MAX_INSTRUCTIONS_CHARS ? raw : null;
+    return { status: "ok", text, text_dropped: text === null, hash, len };
+}
+function parseLeg(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const r = raw;
+    if (typeof r["status"] !== "string")
+        return null;
+    const ln = r["len"];
+    return {
+        status: r["status"],
+        text: typeof r["text"] === "string" ? r["text"] : null,
+        text_dropped: r["text_dropped"] === true,
+        hash: typeof r["hash"] === "string" ? r["hash"] : null,
+        len: Number.isInteger(ln) && ln >= 0 ? ln : null,
+    };
+}
+function parsePin(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const sid = r["server_id"];
+    const at = r["pinned_at"];
+    if (typeof sid !== "string" || sid.length === 0 || typeof at !== "string")
+        return null;
+    const legs = {};
+    const rawLegs = r["legs"];
+    if (rawLegs !== undefined && rawLegs !== null) {
+        if (typeof rawLegs !== "object" || Array.isArray(rawLegs))
+            return null;
+        for (const [name, value] of Object.entries(rawLegs)) {
+            const leg = parseLeg(value);
+            if (leg === null)
+                return null; // a pin with a hole in it would re-pin
+            legs[name] = leg;
+        }
+    }
+    const observed = {};
+    const rawObs = r["observed"];
+    if (rawObs !== null && typeof rawObs === "object" && !Array.isArray(rawObs)) {
+        for (const [name, value] of Object.entries(rawObs)) {
+            const leg = parseLeg(value);
+            if (leg === null)
+                return null;
+            observed[name] = leg;
+        }
+    }
+    const str = (v) => (typeof v === "string" ? v : null);
+    return {
+        server_id: sid,
+        pinned_at: at,
+        via: r["via"] === "manual" ? "manual" : "tofu",
+        protocol_version: str(r["protocol_version"]),
+        observed_via: str(r["observed_via"]),
+        legs,
+        observed,
+        observed_at: str(r["observed_at"]),
+    };
+}
+/** One stem's context pins. Unreadable, non-regular or newer-format files are
+ * tainted and never written. */
+class ContextStore {
+    path;
+    pins = new Map();
+    tainted = null;
+    constructor(path) {
+        this.path = path;
+        this.load();
+    }
+    regular() {
+        try {
+            return lstatSync(this.path).isFile();
+        }
+        catch {
+            return null; // absent
+        }
+    }
+    readDisk() {
+        const regular = this.regular();
+        if (regular === null)
+            return new Map();
+        if (!regular) {
+            this.tainted = "context store is not a regular file";
+            return null;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            this.tainted = "context store is unreadable";
+            return null;
+        }
+        if (raw === null || typeof raw !== "object" || raw["schema_version"] !== CONTEXT_STORE_VERSION) {
+            this.tainted = "context store has an unsupported format";
+            return null;
+        }
+        const out = new Map();
+        const servers = raw["servers"];
+        if (servers !== null && typeof servers === "object" && !Array.isArray(servers)) {
+            for (const [key, value] of Object.entries(servers)) {
+                const pin = parsePin(value);
+                // A record filed under another server's key could overwrite that server's
+                // baseline on the next write. Python taints the same case.
+                if (pin === null || pin.server_id !== key) {
+                    this.tainted = "context store holds an unreadable record";
+                    continue;
+                }
+                out.set(key, pin);
+            }
+        }
+        return out;
+    }
+    load() {
+        const disk = this.readDisk();
+        if (disk !== null)
+            this.pins = disk;
+    }
+    get(serverId) {
+        return this.pins.get(serverId) ?? null;
+    }
+    put(pin) {
+        if (this.tainted !== null)
+            return;
+        const disk = this.readDisk();
+        if (disk === null)
+            return;
+        for (const [key, value] of disk)
+            if (!this.pins.has(key))
+                this.pins.set(key, value);
+        this.pins.set(pin.server_id, pin);
+        const servers = {};
+        for (const key of [...this.pins.keys()].sort())
+            servers[key] = this.pins.get(key);
+        const body = JSON.stringify({ schema_version: CONTEXT_STORE_VERSION, servers }, null, 2) + "\n";
+        const directory = dirname(this.path) || ".";
+        mkdirSync(directory, { recursive: true });
+        const tmp = join(directory, `.ctxpin.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+        const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0);
+        const fd = openSync(tmp, flags, 0o600);
+        try {
+            writeSync(fd, body);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            renameSync(tmp, this.path);
+        }
+        catch (exc) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                // already gone
+            }
+            throw exc;
+        }
+    }
+}
+/** Classify one observation against the pin (Python `observe`). Pure. */
+export function classifyInstructions(pinned, observed, serverId, observedVia, storeTainted) {
+    const obs = (outcome, kinds = [], detail = "") => ({
+        outcome,
+        serverId,
+        kinds,
+        safetyRelevant: kinds.some((k) => SAFETY_KINDS.has(k)),
+        detail,
+    });
+    if (storeTainted)
+        return obs("tainted", [], "context store unreadable");
+    const leg = pinned?.legs[LEG] ?? null;
+    if (leg === null)
+        return obs("pinned");
+    if (leg.hash === observed.hash)
+        return obs("unchanged");
+    let kind;
+    if (leg.hash === null)
+        kind = ChangeKind.INSTRUCTIONS_ADDED;
+    else if (observed.hash === null)
+        kind = ChangeKind.INSTRUCTIONS_REMOVED;
+    else if (leg.text !== null && observed.text !== null && isNumericOnlyDescriptionChange(leg.text, observed.text)) {
+        kind = ChangeKind.INSTRUCTIONS_NUMERIC;
+    }
+    else
+        kind = ChangeKind.INSTRUCTIONS_CHANGED;
+    if (pinned !== null && pinned.observed_via !== null && pinned.observed_via !== observedVia) {
+        return obs("skewed", [kind], `pinned via ${pinned.observed_via}, observed via ${observedVia}`);
+    }
+    if (kind === ChangeKind.INSTRUCTIONS_NUMERIC) {
+        return obs("numeric-unbounded", [kind], "numeric-only change; this SDK does not apply the digit budget");
+    }
+    return obs(SAFETY_KINDS.has(kind) ? "drifted" : "cosmetic", [kind]);
+}
+/** Owns one server's context pin and turns observations into reports. */
+export class ContextWatcher {
+    serverId;
+    onEvent;
+    now;
+    store;
+    storeError = null;
+    constructor(path, serverId, onEvent, now) {
+        this.serverId = serverId;
+        this.onEvent = onEvent;
+        this.now = now;
+        let store = null;
+        try {
+            store = new ContextStore(path);
+        }
+        catch (exc) {
+            this.storeError = exc instanceof Error ? exc.name : "Error";
+        }
+        this.store = store;
+    }
+    get path() {
+        return this.store?.path ?? null;
+    }
+    observe(instructions, observedVia, protocolVersion) {
+        const leg = legFromInstructions(instructions);
+        if (this.store === null) {
+            const failed = {
+                outcome: "unobserved",
+                serverId: this.serverId,
+                kinds: [],
+                safetyRelevant: false,
+                detail: this.storeError ?? "context store unavailable",
+            };
+            this.emit(failed);
+            return failed;
+        }
+        const pin = this.store.get(this.serverId);
+        const result = classifyInstructions(pin, leg, this.serverId, observedVia, this.store.tainted !== null);
+        try {
+            if (result.outcome === "pinned") {
+                this.store.put({
+                    server_id: this.serverId,
+                    pinned_at: this.now(),
+                    via: "tofu",
+                    protocol_version: protocolVersion,
+                    observed_via: observedVia,
+                    legs: { [LEG]: leg },
+                    observed: {},
+                    observed_at: null,
+                });
+            }
+            else if (pin !== null && result.outcome !== "unchanged" && result.outcome !== "tainted") {
+                // Record what was seen without moving the baseline.
+                this.store.put({ ...pin, observed: { [LEG]: leg }, observed_at: this.now() });
+            }
+        }
+        catch {
+            // A failed write costs the record, never the session.
+        }
+        this.emit(result);
+        return result;
+    }
+    emit(obs) {
+        if (obs.outcome === "unchanged")
+            return;
+        try {
+            this.onEvent(obs);
+        }
+        catch {
+            // a report must never perturb the session
+        }
+    }
+}
+//# sourceMappingURL=contextWatch.js.map

package/dist/src/contextWatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextWatch.js","sourceRoot":"","sources":["../../src/contextWatch.ts"],"names":[],"mappings":"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"}

package/dist/src/contractFields.d.ts

@@ -12,7 +12,7 @@
  * pin a key it lacks was never recorded, so it is filled in from the first
  * matching list instead of read as a change.
  */
-export declare const CONTRACT_FIELDS_VERSION = 2;
+export declare const CONTRACT_FIELDS_VERSION = 3;
 /** Where a pin file keeps the marker: inside `schema`, which gate 0.18 and SDK
  * 0.16 keep whole when they rewrite a record. The store moves it out on load and
  * back on write; `extraFields` skips it so a server cannot supply it. */
@@ -26,6 +26,10 @@ export declare function assignOwn(target: Record<string, unknown>, source: Recor
  * matching what pins written by 0.16 stored. */
 export declare function extraFields(entry: unknown): Record<string, unknown>;
 export declare const ANNOTATION_TEXT_KEY = "annotations";
+/** What a normalized definition and a pin keep: `extraFields` plus a title that
+ * is present but not a string. The digest stays on `extraFields`. Mirrors Python
+ * `listed_fields`. */
+export declare function listedFields(entry: unknown): Record<string, unknown>;
 /** What the gate compares on a hash match: the extra fields, plus the
  * annotation keys other than the four hints under one synthetic key that never
  * reaches a pin or a digest. Mirrors Python `compared_fields`. */
@@ -36,6 +40,11 @@ export declare function comparedFields(entry: unknown): Record<string, unknown>;
 export declare function comparedKeys(pinnedSchema: Record<string, unknown>, observed: Record<string, unknown>, complete: boolean): string[];
 /** Extra fields the live entry has and an old pin never recorded. */
 export declare function missingExtraFields(pinnedSchema: Record<string, unknown>, observed: Record<string, unknown>): Record<string, unknown>;
+/** Whether a pin's marker means it recorded every field listed at the time. */
+export declare function isComplete(version: number | undefined): boolean;
+/** What a pin at `version` may record once from a matching list (Python
+ * `fields_to_backfill`): everything it lacks when unmarked, nothing when marked. */
+export declare function fieldsToBackfill(pinnedSchema: Record<string, unknown>, observed: Record<string, unknown>, version: number | undefined): Record<string, unknown>;
 /** A server-chosen key, quoted and escaped for a reason string (Python
  * `json.dumps(key, ensure_ascii=True)`). */
 export declare function fieldLabel(key: string): string;

package/dist/src/contractFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractFields.d.ts","sourceRoot":"","sources":["../../src/contractFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;yEAEyE;AACzE,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D;uDACuD;AACvD,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtF;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhG;AAKD;;gDAEgD;AAChD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUnE;AAOD,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAatE;AAED;;wBAEwB;AACxB,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,OAAO,GAChB,MAAM,EAAE,CAOV;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED;4CAC4C;AAC5C,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C"}
+{"version":3,"file":"contractFields.d.ts","sourceRoot":"","sources":["../../src/contractFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;yEAEyE;AACzE,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D;uDACuD;AACvD,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtF;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhG;AAKD;;gDAEgD;AAChD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUnE;AAOD,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;sBAEsB;AACtB,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMpE;AAED;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAatE;AAED;;wBAEwB;AACxB,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,OAAO,GAChB,MAAM,EAAE,CAOV;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAKD,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAG/D;AAED;oFACoF;AACpF,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAED;4CAC4C;AAC5C,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C"}

package/dist/src/contractFields.js

@@ -12,7 +12,8 @@
  * pin a key it lacks was never recorded, so it is filled in from the first
  * matching list instead of read as a change.
  */
-export const CONTRACT_FIELDS_VERSION = 2;
+// 3 since a non-string title is compared. Any marker from 2 up is complete.
+export const CONTRACT_FIELDS_VERSION = 3;
 /** Where a pin file keeps the marker: inside `schema`, which gate 0.18 and SDK
  * 0.16 keep whole when they rewrite a record. The store moves it out on load and
  * back on write; `extraFields` skips it so a server cannot supply it. */
@@ -52,11 +53,23 @@ const ANNOTATION_HINTS = new Set(["readOnlyHint", "destructiveHint", "idempotent
 // "annotations" itself: `extraFields` never carries a top-level "annotations",
 // so no server key can collide with it.
 export const ANNOTATION_TEXT_KEY = "annotations";
+/** What a normalized definition and a pin keep: `extraFields` plus a title that
+ * is present but not a string. The digest stays on `extraFields`. Mirrors Python
+ * `listed_fields`. */
+export function listedFields(entry) {
+    const out = extraFields(entry);
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+        return out;
+    const title = entry["title"];
+    if (title !== undefined && title !== null && typeof title !== "string")
+        setOwn(out, "title", title);
+    return out;
+}
 /** What the gate compares on a hash match: the extra fields, plus the
  * annotation keys other than the four hints under one synthetic key that never
  * reaches a pin or a digest. Mirrors Python `compared_fields`. */
 export function comparedFields(entry) {
-    const out = extraFields(entry);
+    const out = listedFields(entry);
     if (entry === null || typeof entry !== "object" || Array.isArray(entry))
         return out;
     const ann = entry["annotations"];
@@ -86,7 +99,7 @@ export function comparedKeys(pinnedSchema, observed, complete) {
 }
 /** Extra fields the live entry has and an old pin never recorded. */
 export function missingExtraFields(pinnedSchema, observed) {
-    const have = new Set(Object.keys(extraFields(pinnedSchema)));
+    const have = new Set(Object.keys(listedFields(pinnedSchema)));
     const out = {};
     for (const [key, value] of Object.entries(extraFields(observed))) {
         if (!have.has(key))
@@ -94,6 +107,21 @@ export function missingExtraFields(pinnedSchema, observed) {
     }
     return out;
 }
+// The first marker version that recorded every listed field.
+const FIRST_COMPLETE_VERSION = 2;
+/** Whether a pin's marker means it recorded every field listed at the time. */
+export function isComplete(version) {
+    // No upper bound: a newer writer records a superset.
+    return version !== undefined && Number.isInteger(version) && version >= FIRST_COMPLETE_VERSION;
+}
+/** What a pin at `version` may record once from a matching list (Python
+ * `fields_to_backfill`): everything it lacks when unmarked, nothing when marked. */
+export function fieldsToBackfill(pinnedSchema, observed, version) {
+    // A marked pin records nothing; a non-string title is never recorded.
+    if (!isComplete(version))
+        return missingExtraFields(pinnedSchema, observed);
+    return {};
+}
 /** A server-chosen key, quoted and escaped for a reason string (Python
  * `json.dumps(key, ensure_ascii=True)`). */
 export function fieldLabel(key) {