@mnemonik/shared 5.120.1 → 5.131.2

package/dist/hookTimeouts.d.ts

@@ -13,7 +13,20 @@
  * function. No fetch wrappers here — request shaping stays per-package
  * because each host expresses its hook payloads differently.
  */
-/** Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path. */
+/**
+ * Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path.
+ *
+ * The bootstrap digest is delivered over `injections`, so it rides this 2s
+ * budget. That is intentional and sufficient: the server side
+ * (HooksDispatcher.buildBootstrapDigestPayload) only ever does a Redis GET on
+ * the delivery path — a cold synthesis build is fired in the background
+ * (fire-and-forget) and never awaited, so delivery is always sub-10ms. A cold
+ * cache returns the static `session_bootstrap` directive within this budget
+ * (the "cold-prompt" floor), never a blocked/empty response.
+ *
+ * Invariant: no endpoint on a hook's critical path may await an LLM synthesis
+ * call; client timeouts here only ever need to cover a Redis/DB read.
+ */
 export declare const FETCH_TIMEOUT_MS = 2000;
 /** Telemetry fan-out budget. Drop the metric rather than hold the user. */
 export declare const TELEMETRY_TIMEOUT_MS = 500;

package/dist/hookTimeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hookTimeouts.d.ts","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,+GAA+G;AAC/G,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAIxF"}
+{"version":3,"file":"hookTimeouts.d.ts","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,+GAA+G;AAC/G,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAIxF"}

package/dist/hookTimeouts.js

@@ -13,7 +13,20 @@
  * function. No fetch wrappers here — request shaping stays per-package
  * because each host expresses its hook payloads differently.
  */
-/** Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path. */
+/**
+ * Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path.
+ *
+ * The bootstrap digest is delivered over `injections`, so it rides this 2s
+ * budget. That is intentional and sufficient: the server side
+ * (HooksDispatcher.buildBootstrapDigestPayload) only ever does a Redis GET on
+ * the delivery path — a cold synthesis build is fired in the background
+ * (fire-and-forget) and never awaited, so delivery is always sub-10ms. A cold
+ * cache returns the static `session_bootstrap` directive within this budget
+ * (the "cold-prompt" floor), never a blocked/empty response.
+ *
+ * Invariant: no endpoint on a hook's critical path may await an LLM synthesis
+ * call; client timeouts here only ever need to cover a Redis/DB read.
+ */
 export const FETCH_TIMEOUT_MS = 2000;
 /** Telemetry fan-out budget. Drop the metric rather than hold the user. */
 export const TELEMETRY_TIMEOUT_MS = 500;

package/dist/hookTimeouts.js.map

@@ -1 +1 @@
-{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,+GAA+G;AAC/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,+GAA+G;AAC/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC"}

package/dist/instructions.d.ts

@@ -4,8 +4,27 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.101
- * Updated: 2026-06-23
+ * Version: 2.102
+ * Updated: 2026-06-29
+ *
+ * v2.102 — Strengthened the self-bootstrap trigger to a compelling imperative.
+ *         The v2.101 phrasing ("At the start of a session, unless ... call ...")
+ *         was too soft; agents on a blind first turn skipped it. Real-world hole
+ *         it must cover: Cursor's FIRST chat after an IDE open fires no
+ *         sessionStart (confirmed by hook-stdin capture), and beforeSubmitPrompt
+ *         has NO model-facing output field (only user_message, shown to the
+ *         human) — so neither the silent digest nor the hook's
+ *         session_bootstrap_required directive reaches the model. The MCP
+ *         instruction is the ONLY model-facing channel left for that turn, so it
+ *         now leads with the blind-state check + a hard "FIRST action MUST be
+ *         session_bootstrap, before you reply" and an explicit cwd-REQUIRED
+ *         clause. Still self-scoping: skips when the "Mnemonik project context"
+ *         block is already present (working hook/proxy delivery), so config-B/C
+ *         with live delivery don't double-call. cwd stays host-agnostic — the
+ *         agent passes the project root it is working in (Cursor exposes the
+ *         working dir to HOOKS via the stdin `workspace_roots[0]`, which cwdOf
+ *         already reads; it is NOT an agent-readable env var, so the instruction
+ *         must not name one).
  *
  * v2.101 — Stripped to a single instruction: the session_bootstrap trigger.
  *         MCP instructions are set at Server construction (initialize), before
@@ -77,7 +96,7 @@ export declare function getMcpInstructions(): string;
  * Raw instructions content (always returns the content, ignores env var).
  * Use getMcpInstructions() for production code.
  */
-export declare const MCP_INSTRUCTIONS_RAW = "At the start of a session, unless your context already contains a \"Mnemonik project context\" block, call the session_bootstrap tool with your current working directory as cwd. It loads this project's prior decisions, open tasks, and active policies so you work from accumulated context rather than from scratch.";
+export declare const MCP_INSTRUCTIONS_RAW = "If your context does not contain a block beginning \"Mnemonik project context (cached\", call session_bootstrap before replying or taking any other action \u2014 e.g. session_bootstrap({ cwd: \"/absolute/path/to/project\" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it \u2014 substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.";
 /**
  * Default export for convenience.
  * Note: This respects the MNEMONIK_INSTRUCTIONS_ENABLED env var.

package/dist/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,8TAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,+iBAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}

package/dist/instructions.js

@@ -4,8 +4,27 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.101
- * Updated: 2026-06-23
+ * Version: 2.102
+ * Updated: 2026-06-29
+ *
+ * v2.102 — Strengthened the self-bootstrap trigger to a compelling imperative.
+ *         The v2.101 phrasing ("At the start of a session, unless ... call ...")
+ *         was too soft; agents on a blind first turn skipped it. Real-world hole
+ *         it must cover: Cursor's FIRST chat after an IDE open fires no
+ *         sessionStart (confirmed by hook-stdin capture), and beforeSubmitPrompt
+ *         has NO model-facing output field (only user_message, shown to the
+ *         human) — so neither the silent digest nor the hook's
+ *         session_bootstrap_required directive reaches the model. The MCP
+ *         instruction is the ONLY model-facing channel left for that turn, so it
+ *         now leads with the blind-state check + a hard "FIRST action MUST be
+ *         session_bootstrap, before you reply" and an explicit cwd-REQUIRED
+ *         clause. Still self-scoping: skips when the "Mnemonik project context"
+ *         block is already present (working hook/proxy delivery), so config-B/C
+ *         with live delivery don't double-call. cwd stays host-agnostic — the
+ *         agent passes the project root it is working in (Cursor exposes the
+ *         working dir to HOOKS via the stdin `workspace_roots[0]`, which cwdOf
+ *         already reads; it is NOT an agent-readable env var, so the instruction
+ *         must not name one).
  *
  * v2.101 — Stripped to a single instruction: the session_bootstrap trigger.
  *         MCP instructions are set at Server construction (initialize), before
@@ -63,7 +82,7 @@
  *
  * Token-optimised rewrite (superseded by later instruction rewrites).
  */
-const INSTRUCTIONS_CONTENT = `At the start of a session, unless your context already contains a "Mnemonik project context" block, call the session_bootstrap tool with your current working directory as cwd. It loads this project's prior decisions, open tasks, and active policies so you work from accumulated context rather than from scratch.`;
+const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning "Mnemonik project context (cached", call session_bootstrap before replying or taking any other action — e.g. session_bootstrap({ cwd: "/absolute/path/to/project" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it — substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.`;
 /**
  * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
  * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,MAAM,oBAAoB,GAAG,yTAAyT,CAAC;AAEvV;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,GAAG,GAAI,UAAyE,CAAC,OAAO;QAC5F,EAAE,GAAG,CAAC;IACR,IAAI,GAAG,EAAE,6BAA6B,KAAK,OAAO,EAAE,CAAC;QACnD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,MAAM,oBAAoB,GAAG,8hBAA8hB,CAAC;AAE5jB;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,GAAG,GAAI,UAAyE,CAAC,OAAO;QAC5F,EAAE,GAAG,CAAC;IACR,IAAI,GAAG,EAAE,6BAA6B,KAAK,OAAO,EAAE,CAAC;QACnD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "5.120.1",
+  "version": "5.131.2",
   "description": "Shared constants and utilities for Mnemonik packages",
   "type": "module",
   "main": "dist/index.js",

package/src/hookTimeouts.ts

@@ -14,7 +14,20 @@
  * because each host expresses its hook payloads differently.
  */
 
-/** Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path. */
+/**
+ * Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path.
+ *
+ * The bootstrap digest is delivered over `injections`, so it rides this 2s
+ * budget. That is intentional and sufficient: the server side
+ * (HooksDispatcher.buildBootstrapDigestPayload) only ever does a Redis GET on
+ * the delivery path — a cold synthesis build is fired in the background
+ * (fire-and-forget) and never awaited, so delivery is always sub-10ms. A cold
+ * cache returns the static `session_bootstrap` directive within this budget
+ * (the "cold-prompt" floor), never a blocked/empty response.
+ *
+ * Invariant: no endpoint on a hook's critical path may await an LLM synthesis
+ * call; client timeouts here only ever need to cover a Redis/DB read.
+ */
 export const FETCH_TIMEOUT_MS = 2000;
 
 /** Telemetry fan-out budget. Drop the metric rather than hold the user. */

package/src/instructions.ts

@@ -4,8 +4,27 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.101
- * Updated: 2026-06-23
+ * Version: 2.102
+ * Updated: 2026-06-29
+ *
+ * v2.102 — Strengthened the self-bootstrap trigger to a compelling imperative.
+ *         The v2.101 phrasing ("At the start of a session, unless ... call ...")
+ *         was too soft; agents on a blind first turn skipped it. Real-world hole
+ *         it must cover: Cursor's FIRST chat after an IDE open fires no
+ *         sessionStart (confirmed by hook-stdin capture), and beforeSubmitPrompt
+ *         has NO model-facing output field (only user_message, shown to the
+ *         human) — so neither the silent digest nor the hook's
+ *         session_bootstrap_required directive reaches the model. The MCP
+ *         instruction is the ONLY model-facing channel left for that turn, so it
+ *         now leads with the blind-state check + a hard "FIRST action MUST be
+ *         session_bootstrap, before you reply" and an explicit cwd-REQUIRED
+ *         clause. Still self-scoping: skips when the "Mnemonik project context"
+ *         block is already present (working hook/proxy delivery), so config-B/C
+ *         with live delivery don't double-call. cwd stays host-agnostic — the
+ *         agent passes the project root it is working in (Cursor exposes the
+ *         working dir to HOOKS via the stdin `workspace_roots[0]`, which cwdOf
+ *         already reads; it is NOT an agent-readable env var, so the instruction
+ *         must not name one).
  *
  * v2.101 — Stripped to a single instruction: the session_bootstrap trigger.
  *         MCP instructions are set at Server construction (initialize), before
@@ -64,7 +83,7 @@
  * Token-optimised rewrite (superseded by later instruction rewrites).
  */
 
-const INSTRUCTIONS_CONTENT = `At the start of a session, unless your context already contains a "Mnemonik project context" block, call the session_bootstrap tool with your current working directory as cwd. It loads this project's prior decisions, open tasks, and active policies so you work from accumulated context rather than from scratch.`;
+const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning "Mnemonik project context (cached", call session_bootstrap before replying or taking any other action — e.g. session_bootstrap({ cwd: "/absolute/path/to/project" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it — substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.`;
 
 /**
  * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.