@absolutejs/mcp 0.17.4 → 0.17.6

package/CHANGELOG.md

@@ -6,6 +6,22 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.17.6 — 2026-09-11
+
+### Added
+
+- **Allow verified patched hosts through the version fallback with optional Apps configuration** (`clientSupportsMcpApps`, `McpAppsConfig`)
+
+### Fixed
+
+- **Use text and structured report results on affected VS Code builds while their upstream webview startup race remains unresolved**
+
+## 0.17.5 — 2026-09-11
+
+### Added
+
+- **Distribute a verified VS Code webview startup-race source patch and actual-method regression checker, with explicit upstream delivery requirements**
+
 ## 0.17.4 — 2026-09-11
 
 ### Added

package/UPSTREAM_ISSUES.md

@@ -0,0 +1,19 @@
+# Upstream issues
+
+## VS Code webviews can go blank after a remount
+
+Tracking: [microsoft/vscode#335908](https://github.com/microsoft/vscode/issues/335908). An issue was submitted; no pull request was submitted.
+
+An earlier asynchronous origin-hash completion can replace the iframe after a newer mount connects. In native Windows VS Code 1.135.0, delaying the first hash reproduced a blank report. A current-promise guard passed three rounds across balance, usage and receipts in the isolated test process. The same unguarded method was found in the local 1.136.1 bundle; that version was source-inspected, not runtime-tested. See [the source patch and regression checker](canary/vscode/README.md).
+
+### Shared workaround in MCP 0.17.6
+
+New sessions identifying themselves as `Visual Studio Code` version `1.135.0` or `1.136.1` receive text and structured results without Apps metadata or HTML resources. Report tools remain available. Authorization, billing and other host negotiations are unchanged. This exact-version rule is a presentation workaround, not a security boundary or a certification of other versions.
+
+For an existing VS Code connection, run **MCP: Reset Cached Tools**, then **Developer: Reload Window**, reconnect/start the MCP server and open a new chat. Reconnection alone reused old UI metadata in our test. Reconnect the MCP server after upgrading: the negotiated Apps capability is stored in the session, so existing sessions retain their old decision. Consumers get the workaround through the package; they do not need a project-specific renderer or an editor patch.
+
+`apps.allowKnownBrokenHosts: true` bypasses the version exclusion for controlled testing of a verified patched host. It still requires the host to advertise the Apps MIME capability. Do not enable it on ordinary affected installations. The diagnostic in-memory VS Code patch does not survive restart and is not the deployed workaround.
+
+### Removal
+
+Keep the fallback for affected builds until they can reliably render Apps. When an upstream fix ships, verify fresh conversations, repeated mounts, refresh and pagination in the released host before certifying rich views there. Remove the override when a patched test build is retired. Keep the source regression and issue history so a successful retry is not mistaken for a fix.

package/canary/vscode/README.md

@@ -0,0 +1,33 @@
+# VS Code webview mount race
+
+A host lifecycle race can leave an MCP App blank before its inner document loads. `mountTo` computes the parent-origin hash asynchronously. A subsequent mount can finish first; without a current-startup check, the older completion can overwrite the origin and reset the iframe after the newer connection is ready.
+
+`webview-mount-race.patch` fixes the host's source implementation by applying a completion only when its captured promise is still the current mount promise. It does not change MCP or billing code, disable sandboxing, retry tools, or add an arbitrary delay.
+
+The baseline is VS Code 1.135.0, commit `08d4889f9ec4a1685d257b9b95de036c8e1ce1e5`. The same mount method was present on upstream main when checked September 11, 2026. [Upstream source](https://github.com/microsoft/vscode/blob/08d4889f9ec4a1685d257b9b95de036c8e1ce1e5/src/vs/workbench/contrib/webview/browser/webviewElement.ts).
+
+## Reproduce and check the source fix
+
+Use a trusted VS Code checkout and the package's Bun checker. The checker extracts and executes the actual `mountTo` method; it does not substitute a second implementation. Other DOM/service hooks are stubbed, and hash completion order is controlled.
+
+```sh
+bun /path/to/node_modules/@absolutejs/mcp/canary/vscode/check-mount.ts src/vs/workbench/contrib/webview/browser/webviewElement.ts
+# Original: exits 1 for both obsolete-startup checks.
+git apply /path/to/node_modules/@absolutejs/mcp/canary/vscode/webview-mount-race.patch
+bun /path/to/node_modules/@absolutejs/mcp/canary/vscode/check-mount.ts src/vs/workbench/contrib/webview/browser/webviewElement.ts
+# Patched: all four checks pass; exits 0.
+```
+
+The checker executes code from the supplied source file. Use only a trusted checkout. It needs Bun and is a targeted lifecycle regression, not the complete VS Code test suite.
+
+## Native-host verification
+
+In the isolated, signed-in native Windows VS Code 1.135.0 test window, completing an earlier origin hash 350ms after a newer startup reproduced a blank report on the unmodified host. With the equivalent current-promise guard applied only in the test process, three repeated rounds across balance, usage and receipts rendered all views without reloading. Both source-level completion orders now pass, and disposed views remain excluded. No paid tools or customer data were used.
+
+Some unmodified first-load runs passed too: this is a timing-sensitive failure, and ordinary successful retries do not prove it fixed. The controlled race provides the regression. Additional host defects remain possible; this patch addresses the demonstrated obsolete-startup race.
+
+## Delivery status
+
+The bug is reported in [microsoft/vscode#335908](https://github.com/microsoft/vscode/issues/335908); no PR was submitted. This package distributes the source patch and checker for review, but does not modify installed editors. The test-process patch disappears on restart.
+
+MCP 0.17.6 instead defaults affected versions to text and structured reports. Reconnect after upgrading to negotiate the fallback. See [UPSTREAM_ISSUES.md](../../UPSTREAM_ISSUES.md) for the exact version scope, diagnostic override and removal conditions. Rich first-load support remains unverified in an unmodified released host.

package/canary/vscode/check-mount.ts

@@ -0,0 +1,75 @@
+/** Run against a trusted VS Code webviewElement.ts checkout; executes its real mountTo method. */
+import { readFile } from "node:fs/promises";
+const file = process.argv[2];
+if (!file) throw Error("Usage: bun check-mount.ts /path/to/webviewElement.ts");
+const source = await readFile(file, "utf8");
+const start = source.indexOf("\tpublic mountTo(");
+const end = source.indexOf("\n\tprivate _registerMessageHandler(", start);
+if (start < 0 || end < 0) throw Error("Unsupported source layout");
+const method = source.slice(start, end);
+const javascript = new Bun.Transpiler({ loader: "ts" }).transformSync(
+  `class MountProbe { ${method} }`,
+);
+type Probe = {
+  mountTo: (element: unknown, window: unknown) => void;
+  _encodedWebviewOrigin?: string;
+  _disposed: boolean;
+};
+const results: { name: string; passed: boolean }[] = [];
+for (const order of [
+  [1, 0],
+  [0, 1],
+]) {
+  const pending: ((origin: string) => void)[] = [];
+  const mounted: string[] = [];
+  const create = new Function(
+    "parentOriginHash",
+    "EventType",
+    "addDisposableListener",
+    `${javascript};return MountProbe;`,
+  );
+  const Constructor = create(
+    () => new Promise<string>((resolve) => pending.push(resolve)),
+    {},
+    () => ({}),
+  ) as new () => Probe;
+  const probe = new Constructor();
+  Object.assign(probe, {
+    element: {},
+    origin: "test",
+    _disposed: false,
+    _registerMessageHandler: () => {},
+    _register: () => {},
+    perfMark: () => {},
+    _initElement: (origin: string) => mounted.push(origin),
+  });
+  const container = { appendChild: () => {} };
+  probe.mountTo(container, { origin: "first-window", vscodeWindowId: 1 });
+  probe.mountTo(container, { origin: "second-window", vscodeWindowId: 2 });
+  for (const index of order) {
+    pending[index]!(index === 0 ? "old-origin" : "new-origin");
+    await new Promise<void>((resolve) => queueMicrotask(resolve));
+  }
+  results.push({
+    name:
+      order[0] === 1
+        ? "late-old-startup-ignored"
+        : "early-obsolete-startup-ignored",
+    passed:
+      mounted.length === 1 &&
+      mounted[0] === "new-origin" &&
+      probe._encodedWebviewOrigin === "new-origin",
+  });
+  mounted.length = 0;
+  probe.mountTo(container, { origin: "disposed-window", vscodeWindowId: 3 });
+  probe._disposed = true;
+  pending[2]!("disposed-origin");
+  await new Promise<void>((resolve) => queueMicrotask(resolve));
+  results.push({
+    name: "disposed-view-not-mounted",
+    passed: mounted.length === 0,
+  });
+}
+const passed = results.every((result) => result.passed);
+console.log(JSON.stringify({ passed, results }, null, 2));
+if (!passed) process.exitCode = 1;

package/canary/vscode/webview-mount-race.patch

@@ -0,0 +1,22 @@
+--- a/src/vs/workbench/contrib/webview/browser/webviewElement.ts
++++ b/src/vs/workbench/contrib/webview/browser/webviewElement.ts
+@@ -477,9 +477,16 @@
+ 		}
+ 
+ 		this._windowId = targetWindow.vscodeWindowId;
+-		this._encodedWebviewOriginPromise = parentOriginHash(targetWindow.origin, this.origin).then(id => this._encodedWebviewOrigin = id);
+-		this._encodedWebviewOriginPromise.then(encodedWebviewOrigin => {
+-			if (!this._disposed) {
++		const encodedWebviewOriginPromise = parentOriginHash(targetWindow.origin, this.origin).then(id => {
++			if (this._encodedWebviewOriginPromise === encodedWebviewOriginPromise) {
++				this._encodedWebviewOrigin = id;
++			}
++			return id;
++		});
++		this._encodedWebviewOriginPromise = encodedWebviewOriginPromise;
++		encodedWebviewOriginPromise.then(encodedWebviewOrigin => {
++			// A remount may supersede this startup before its origin hash resolves.
++			if (!this._disposed && this._encodedWebviewOriginPromise === encodedWebviewOriginPromise) {
+ 				this._initElement(encodedWebviewOrigin, this.extension, this._options, targetWindow);
+ 			}
+ 		});

package/changelog.json

@@ -2,6 +2,34 @@
   "contract": 1,
   "name": "@absolutejs/mcp",
   "releases": [
+    {
+      "version": "0.17.6",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "fixed",
+          "summary": "Use text and structured report results on affected VS Code builds while their upstream webview startup race remains unresolved"
+        },
+        {
+          "kind": "added",
+          "summary": "Allow verified patched hosts through the version fallback with optional Apps configuration",
+          "symbols": [
+            "clientSupportsMcpApps",
+            "McpAppsConfig"
+          ]
+        }
+      ]
+    },
+    {
+      "version": "0.17.5",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Distribute a verified VS Code webview startup-race source patch and actual-method regression checker, with explicit upstream delivery requirements"
+        }
+      ]
+    },
     {
       "version": "0.17.4",
       "date": "2026-09-11",

package/dist/apps.js

@@ -49,9 +49,11 @@ var createBillingApps = () => {
 
 // src/apps.ts
 var MCP_APP_MIME = "text/html;profile=mcp-app";
-var clientSupportsMcpApps = (params) => {
+var clientSupportsMcpApps = (params, options = {}) => {
   if (!isRecord(params) || !isRecord(params.capabilities) || !isRecord(params.capabilities.extensions))
     return false;
+  if (!options.allowKnownBrokenHosts && isRecord(params.clientInfo) && params.clientInfo.name === "Visual Studio Code" && (params.clientInfo.version === "1.135.0" || params.clientInfo.version === "1.136.1"))
+    return false;
   const ui = params.capabilities.extensions["io.modelcontextprotocol/ui"];
   return isRecord(ui) && Array.isArray(ui.mimeTypes) && ui.mimeTypes.includes(MCP_APP_MIME);
 };

package/dist/index.js

@@ -49,9 +49,11 @@ var createBillingApps = () => {
 
 // src/apps.ts
 var MCP_APP_MIME = "text/html;profile=mcp-app";
-var clientSupportsMcpApps = (params) => {
+var clientSupportsMcpApps = (params, options = {}) => {
   if (!isRecord(params) || !isRecord(params.capabilities) || !isRecord(params.capabilities.extensions))
     return false;
+  if (!options.allowKnownBrokenHosts && isRecord(params.clientInfo) && params.clientInfo.name === "Visual Studio Code" && (params.clientInfo.version === "1.135.0" || params.clientInfo.version === "1.136.1"))
+    return false;
   const ui = params.capabilities.extensions["io.modelcontextprotocol/ui"];
   return isRecord(ui) && Array.isArray(ui.mimeTypes) && ui.mimeTypes.includes(MCP_APP_MIME);
 };
@@ -1379,7 +1381,7 @@ var initialize = async (config, id, params, context) => {
   if (!config.elicitation?.enabled && !config.apps || !context.sessions)
     return response;
   const elicitation = clientElicitation(params);
-  const sessionId = await context.sessions.create(elicitation.form || elicitation.url, elicitation.url, Boolean(config.apps) && clientSupportsMcpApps(params));
+  const sessionId = await context.sessions.create(elicitation.form || elicitation.url, elicitation.url, Boolean(config.apps) && clientSupportsMcpApps(params, config.apps));
   response.headers.set("Mcp-Session-Id", sessionId);
   return response;
 };

package/dist/src/apps.d.ts

@@ -5,11 +5,13 @@ export type McpAppResource = {
     html: string;
 };
 export type McpAppsConfig = {
+    /** Only enable for a host build whose upstream rendering fix has been verified. */
+    allowKnownBrokenHosts?: boolean;
     resources: Record<string, McpAppResource>;
     store?: McpSessionStore;
 };
 /** Capability is presentation only; never a commerce or authorization decision. */
-export declare const clientSupportsMcpApps: (params: unknown) => boolean;
+export declare const clientSupportsMcpApps: (params: unknown, options?: Pick<McpAppsConfig, "allowKnownBrokenHosts">) => boolean;
 export declare const withMcpApp: (tool: McpTool, resourceUri: string) => McpTool;
 /** Offline templates: all data comes through authenticated tool results and the
  * official host bridge. Network, nested frames and privileged permissions are not requested. */

package/docs/host-canaries.md

@@ -93,3 +93,13 @@ const report = await runAuthenticatedCanary({
 Choose two accounts with known distinct data. The canary refuses identical results as inconclusive and verifies repeated reads remain stable. It checks both directions of session-ID substitution: rejecting the foreign session or returning the currently authenticated account's result is acceptable. It also checks missing/invalid credentials, unauthorized DELETE, authorized deletion, terminated-session 404, and fresh initialization/read. It creates and cleans up only its own MCP sessions, never purchases or modifies account data. Read-only annotations are a prerequisite, not a substitute for the operator selecting a known non-billable read tool. The current harness requires JSON RPC responses; SSE-only servers are not certified by it.
 
 This verifies the selected read path, not every tenant resource, token revocation, automatic host reconnect, or billing permissions. Session termination is explicit DELETE; timed TTL expiry needs a separate store test. Use dedicated test clients and remove their grants after verification. Do not publish tokens, transcripts, fingerprints, or raw account data.
+
+## VS Code first-load race identified
+
+MCP 0.17.5 includes `canary/vscode/README.md`, a VS Code source patch and an executable actual-method regression. A controlled out-of-order origin-hash completion reproduces a blank view in native VS Code 1.135.0. The candidate current-promise guard passed three rounds across all three report views and both source-level completion orders. This is a host fix, not an MCP renderer change. The package distributes the patch for review; it does not modify installed editors or certify an upstream release. First-load activation remains blocked until a supported host containing the fix is verified.
+
+## Temporary VS Code fallback (0.17.6)
+
+The issue is tracked in [microsoft/vscode#335908](https://github.com/microsoft/vscode/issues/335908). Known affected versions now receive text and structured reports on new sessions, keeping tools usable without invoking the faulty webview path. Other hosts retain their negotiated presentation. See [UPSTREAM_ISSUES.md](../UPSTREAM_ISSUES.md) for scope and removal conditions. This workaround does not certify rich rendering on affected editors.
+
+Native Windows VS Code 1.135.0 verification: after removing the in-memory editor patch, reconnecting alone left cached UI metadata and produced resource errors. Running **MCP: Reset Cached Tools**, reloading the window and opening a new chat cleared it. The final run returned all three reports as visible text, with three successful tool calls, no resource reads and no App frames. This is a verified text fallback, not rich rendering evidence.

package/package.json

@@ -72,7 +72,8 @@
     "docs/mcp-apps.md",
     "docs/third-party",
     "canary",
-    "docs/host-canaries.md"
+    "docs/host-canaries.md",
+    "UPSTREAM_ISSUES.md"
   ],
   "scripts": {
     "build": "bun run build:apps && rm -rf dist && bun build src/index.ts src/manifest.ts src/commerce.ts src/apps.ts --outdir dist --root ./src --target=bun --external @absolutejs/agency --external '@absolutejs/agency/*' --external elysia && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
@@ -84,8 +85,8 @@
     "prepublishOnly": "bun run check:package",
     "build:apps": "bun scripts/build-apps.ts",
     "canary": "bun canary/server.ts",
-    "check:canary": "tsc --noEmit --strict --skipLibCheck --moduleResolution bundler --module esnext --target esnext --types bun canary/server.ts canary/authenticated.ts"
+    "check:canary": "tsc --noEmit --strict --skipLibCheck --moduleResolution bundler --module esnext --target esnext --types bun canary/server.ts canary/authenticated.ts canary/vscode/check-mount.ts"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.17.4"
+  "version": "0.17.6"
 }