@ethisyscore/extension-runtime 1.58.0 → 1.61.0

package/dist/{transport-CHa8ESUx.d.ts → transport-BPwasdNz.d.ts}

@@ -1,5 +1,94 @@
 import { U as UploadDocumentMeta, d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope } from './bridge-envelopes-DA6vxbyb.js';
 
+/**
+ * Version-skew detection for host-side MCP calls.
+ *
+ * A mounted plugin surface holds a capability token minted against the extension version that
+ * was active when the page loaded. When the install is upgraded underneath it, the kernel stops
+ * honouring that token: it rejects with `401` and
+ * `X-Capability-Token-Rejection-Reason: ExtensionVersionMismatch`. Every other rejection reason is
+ * terminal for the surface, but this one is recoverable — remounting against the new version fixes
+ * it — which is why it is worth telling apart from an ordinary auth failure.
+ *
+ * Two signals are handled here, and the difference matters:
+ *
+ * - **Reactive**, from a rejection: the call already failed. Recovery costs the user a round trip
+ *   and whatever in-page state the remount discards.
+ * - **Proactive**, from the version stamped on a *successful* response: the surface learns the
+ *   install moved while it is still working, and can remount at a moment of its choosing. Reads
+ *   keep succeeding until the token's own version check catches up, so this is the path that
+ *   avoids a visible failure altogether.
+ *
+ * The interpretation lives here rather than in each host application so that "which reason means
+ * remount" is decided once, in code that can be tested, instead of being re-derived by every
+ * embedder from HTTP trivia.
+ */
+/** Response header naming the extension version a request was served as. */
+declare const EXTENSION_VERSION_HEADER = "x-extension-version";
+/** Response header naming the version a rejected surface must remount at. */
+declare const EXTENSION_ACTIVE_VERSION_HEADER = "x-extension-active-version";
+/** Response header carrying the kernel's structured capability-token rejection reason. */
+declare const CAPABILITY_REJECTION_REASON_HEADER = "x-capability-token-rejection-reason";
+/** The one rejection reason a surface can resolve by remounting. */
+declare const VERSION_MISMATCH_REASON = "extensionversionmismatch";
+/**
+ * What the host observed about an MCP response, beyond its payload. Both fields are optional
+ * because the {@link McpHttpClient} contract predates them: an implementation that does not supply
+ * them simply never reports skew, which is the previous behaviour rather than a new failure.
+ */
+interface McpResponseMetadata {
+    /** HTTP status code, when the implementation surfaces it. */
+    readonly status?: number;
+    /** Response headers. Looked up case-insensitively, so any casing is fine. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * How skew came to light.
+ *
+ * - `"rejection"` — a call was refused because the surface's token is stale. Recovery costs a round
+ *   trip and whatever in-page state the remount discards.
+ * - `"response-stamp"` — a call succeeded, but the install has moved on. The surface can remount
+ *   before anything fails, so this is the path worth preferring.
+ */
+type VersionSkewSource = "rejection" | "response-stamp";
+/**
+ * The result of one host-side MCP call: the payload the plugin asked for, plus whatever the host
+ * observed about the response itself.
+ *
+ * Named rather than inlined at the {@link McpHttpClient} declaration so hosts have a type to
+ * implement against, and so the skew detector and the transports agree on one shape instead of
+ * three structurally-compatible copies drifting apart.
+ */
+interface McpHttpResponse extends McpResponseMetadata {
+    /** Whether the call succeeded. */
+    readonly ok: boolean;
+    /** The response payload, shaped by the request kind. */
+    readonly data?: unknown;
+    /** Failure message when {@link ok} is false. */
+    readonly error?: string;
+}
+/** A detected mismatch between the version a surface is running and the version now installed. */
+interface VersionSkew {
+    /**
+     * The version to remount at, when the kernel named it. Undefined means skew is certain but the
+     * target is not — the surface should re-read the extension descriptor rather than guess.
+     */
+    readonly activeVersion?: string;
+    /** Which signal detected the skew. */
+    readonly detectedFrom: VersionSkewSource;
+}
+/**
+ * Decides whether an MCP response means the surface is running against a version that is no longer
+ * installed.
+ *
+ * @param response What the host observed: whether the call succeeded, plus any status and headers.
+ * @param mountedExtensionVersion The version this surface mounted at. Required for proactive
+ * detection — without it a response stamp cannot be compared to anything, and only rejections are
+ * detectable.
+ * @returns The skew, or `null` when the response says nothing about versions.
+ */
+declare function detectVersionSkew(response: McpHttpResponse, mountedExtensionVersion?: string): VersionSkew | null;
+
 /**
  * Worker-side host transport for `renderMode: remote-runtime` extensions
  * (Contract B). Owns the lifecycle of:
@@ -80,11 +169,12 @@ interface McpUploadRequest {
  * branch until updated (the FE upload hook is inert until the host handles it).
  */
 interface McpHttpClient {
-    fetch(request: McpHttpRequest): Promise<{
-        ok: boolean;
-        data?: unknown;
-        error?: string;
-    }>;
+    /**
+     * Performs the call. The response's `status` and `headers` are optional and additive: supplying
+     * them is what enables version-skew detection (see {@link detectVersionSkew}), and an
+     * implementation that omits them behaves exactly as before rather than failing.
+     */
+    fetch(request: McpHttpRequest): Promise<McpHttpResponse>;
 }
 /**
  * Construction options for {@link WorkerRemoteDomTransport}.
@@ -108,6 +198,20 @@ interface WorkerRemoteDomTransportOptions {
      * back through the port.
      */
     mcpClient: McpHttpClient;
+    /**
+     * The extension version this surface mounted at. Supplying it enables *proactive* skew
+     * detection: a successful response stamped with a different version means the install moved
+     * while the surface is still working, so it can remount before anything fails. Without it only
+     * outright rejections are detectable, which is a worse experience but not a broken one.
+     */
+    mountedExtensionVersion?: string;
+    /**
+     * Called at most once, when this surface is found to be running against a version that is no
+     * longer installed. The host is expected to remount the surface (which re-mints a capability
+     * token against the new version); the transport itself does not retry, because the pending call
+     * belongs to a page that is about to be replaced.
+     */
+    onVersionSkew?: (skew: VersionSkew) => void;
     /**
      * Injectable Worker constructor (tests use a fake). Defaults to the
      * global `Worker`.
@@ -216,6 +320,9 @@ declare class WorkerRemoteDomTransport {
     private readonly workerPort;
     private readonly mcpClient;
     private readonly capabilityTokenProvider;
+    private readonly mountedExtensionVersion?;
+    private readonly onVersionSkew?;
+    private versionSkewReported;
     private readonly coalesceMs;
     private readonly maxConcurrentMcpRequests;
     private readonly abortController;
@@ -357,10 +464,25 @@ declare class WorkerRemoteDomTransport {
      * to the dispose-level controller.
      */
     private requestSignal;
+    /**
+     * Raises the skew callback the first time this surface is seen to be running against a version
+     * that is no longer installed.
+     *
+     * Latched deliberately. A page typically has several MCP calls in flight, and after an upgrade
+     * every one of them reports the same skew — firing per response would ask the host to remount
+     * the same surface repeatedly, and the second remount would tear down the first. One signal per
+     * transport is all a remount needs, and the transport is discarded along with the surface.
+     *
+     * The callback is host code, so it is assumed to be able to throw. Two consequences are guarded
+     * here: the throw must not escape into the MCP handler's catch (which would reply `ok: false`
+     * for a call that actually succeeded), and it must not consume the latch (which would leave the
+     * surface with no response AND no further chance of being told to remount).
+     */
+    private reportVersionSkew;
     private handleInvokeTool;
     private handleGetResource;
     private handleUploadDocument;
     private replyError;
 }
 
-export { DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, type InputEventPayload as I, type McpHttpClient as M, WORKER_TRANSPORT_PROTOCOL as W, type McpHttpRequest as a, type McpUploadRequest as b, type WorkerCtor as c, type WorkerHandshakePayload as d, type WorkerLike as e, WorkerRemoteDomTransport as f, type WorkerRemoteDomTransportOptions as g };
+export { CAPABILITY_REJECTION_REASON_HEADER as C, DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, EXTENSION_ACTIVE_VERSION_HEADER as E, type InputEventPayload as I, type McpHttpClient as M, VERSION_MISMATCH_REASON as V, WORKER_TRANSPORT_PROTOCOL as W, EXTENSION_VERSION_HEADER as a, type McpHttpRequest as b, type McpHttpResponse as c, type McpResponseMetadata as d, type McpUploadRequest as e, type VersionSkew as f, type VersionSkewSource as g, type WorkerCtor as h, type WorkerHandshakePayload as i, type WorkerLike as j, WorkerRemoteDomTransport as k, type WorkerRemoteDomTransportOptions as l, detectVersionSkew as m };

package/dist/{transport-DJE6ljme.d.cts → transport-BbSPAS_N.d.cts}

@@ -1,5 +1,94 @@
 import { U as UploadDocumentMeta, d as BridgePushThemeEnvelope, c as BridgePushLocaleEnvelope, b as BridgePushDensityEnvelope, a as BridgePushA11yEnvelope, B as BridgeNavPushEnvelope } from './bridge-envelopes-DA6vxbyb.cjs';
 
+/**
+ * Version-skew detection for host-side MCP calls.
+ *
+ * A mounted plugin surface holds a capability token minted against the extension version that
+ * was active when the page loaded. When the install is upgraded underneath it, the kernel stops
+ * honouring that token: it rejects with `401` and
+ * `X-Capability-Token-Rejection-Reason: ExtensionVersionMismatch`. Every other rejection reason is
+ * terminal for the surface, but this one is recoverable — remounting against the new version fixes
+ * it — which is why it is worth telling apart from an ordinary auth failure.
+ *
+ * Two signals are handled here, and the difference matters:
+ *
+ * - **Reactive**, from a rejection: the call already failed. Recovery costs the user a round trip
+ *   and whatever in-page state the remount discards.
+ * - **Proactive**, from the version stamped on a *successful* response: the surface learns the
+ *   install moved while it is still working, and can remount at a moment of its choosing. Reads
+ *   keep succeeding until the token's own version check catches up, so this is the path that
+ *   avoids a visible failure altogether.
+ *
+ * The interpretation lives here rather than in each host application so that "which reason means
+ * remount" is decided once, in code that can be tested, instead of being re-derived by every
+ * embedder from HTTP trivia.
+ */
+/** Response header naming the extension version a request was served as. */
+declare const EXTENSION_VERSION_HEADER = "x-extension-version";
+/** Response header naming the version a rejected surface must remount at. */
+declare const EXTENSION_ACTIVE_VERSION_HEADER = "x-extension-active-version";
+/** Response header carrying the kernel's structured capability-token rejection reason. */
+declare const CAPABILITY_REJECTION_REASON_HEADER = "x-capability-token-rejection-reason";
+/** The one rejection reason a surface can resolve by remounting. */
+declare const VERSION_MISMATCH_REASON = "extensionversionmismatch";
+/**
+ * What the host observed about an MCP response, beyond its payload. Both fields are optional
+ * because the {@link McpHttpClient} contract predates them: an implementation that does not supply
+ * them simply never reports skew, which is the previous behaviour rather than a new failure.
+ */
+interface McpResponseMetadata {
+    /** HTTP status code, when the implementation surfaces it. */
+    readonly status?: number;
+    /** Response headers. Looked up case-insensitively, so any casing is fine. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * How skew came to light.
+ *
+ * - `"rejection"` — a call was refused because the surface's token is stale. Recovery costs a round
+ *   trip and whatever in-page state the remount discards.
+ * - `"response-stamp"` — a call succeeded, but the install has moved on. The surface can remount
+ *   before anything fails, so this is the path worth preferring.
+ */
+type VersionSkewSource = "rejection" | "response-stamp";
+/**
+ * The result of one host-side MCP call: the payload the plugin asked for, plus whatever the host
+ * observed about the response itself.
+ *
+ * Named rather than inlined at the {@link McpHttpClient} declaration so hosts have a type to
+ * implement against, and so the skew detector and the transports agree on one shape instead of
+ * three structurally-compatible copies drifting apart.
+ */
+interface McpHttpResponse extends McpResponseMetadata {
+    /** Whether the call succeeded. */
+    readonly ok: boolean;
+    /** The response payload, shaped by the request kind. */
+    readonly data?: unknown;
+    /** Failure message when {@link ok} is false. */
+    readonly error?: string;
+}
+/** A detected mismatch between the version a surface is running and the version now installed. */
+interface VersionSkew {
+    /**
+     * The version to remount at, when the kernel named it. Undefined means skew is certain but the
+     * target is not — the surface should re-read the extension descriptor rather than guess.
+     */
+    readonly activeVersion?: string;
+    /** Which signal detected the skew. */
+    readonly detectedFrom: VersionSkewSource;
+}
+/**
+ * Decides whether an MCP response means the surface is running against a version that is no longer
+ * installed.
+ *
+ * @param response What the host observed: whether the call succeeded, plus any status and headers.
+ * @param mountedExtensionVersion The version this surface mounted at. Required for proactive
+ * detection — without it a response stamp cannot be compared to anything, and only rejections are
+ * detectable.
+ * @returns The skew, or `null` when the response says nothing about versions.
+ */
+declare function detectVersionSkew(response: McpHttpResponse, mountedExtensionVersion?: string): VersionSkew | null;
+
 /**
  * Worker-side host transport for `renderMode: remote-runtime` extensions
  * (Contract B). Owns the lifecycle of:
@@ -80,11 +169,12 @@ interface McpUploadRequest {
  * branch until updated (the FE upload hook is inert until the host handles it).
  */
 interface McpHttpClient {
-    fetch(request: McpHttpRequest): Promise<{
-        ok: boolean;
-        data?: unknown;
-        error?: string;
-    }>;
+    /**
+     * Performs the call. The response's `status` and `headers` are optional and additive: supplying
+     * them is what enables version-skew detection (see {@link detectVersionSkew}), and an
+     * implementation that omits them behaves exactly as before rather than failing.
+     */
+    fetch(request: McpHttpRequest): Promise<McpHttpResponse>;
 }
 /**
  * Construction options for {@link WorkerRemoteDomTransport}.
@@ -108,6 +198,20 @@ interface WorkerRemoteDomTransportOptions {
      * back through the port.
      */
     mcpClient: McpHttpClient;
+    /**
+     * The extension version this surface mounted at. Supplying it enables *proactive* skew
+     * detection: a successful response stamped with a different version means the install moved
+     * while the surface is still working, so it can remount before anything fails. Without it only
+     * outright rejections are detectable, which is a worse experience but not a broken one.
+     */
+    mountedExtensionVersion?: string;
+    /**
+     * Called at most once, when this surface is found to be running against a version that is no
+     * longer installed. The host is expected to remount the surface (which re-mints a capability
+     * token against the new version); the transport itself does not retry, because the pending call
+     * belongs to a page that is about to be replaced.
+     */
+    onVersionSkew?: (skew: VersionSkew) => void;
     /**
      * Injectable Worker constructor (tests use a fake). Defaults to the
      * global `Worker`.
@@ -216,6 +320,9 @@ declare class WorkerRemoteDomTransport {
     private readonly workerPort;
     private readonly mcpClient;
     private readonly capabilityTokenProvider;
+    private readonly mountedExtensionVersion?;
+    private readonly onVersionSkew?;
+    private versionSkewReported;
     private readonly coalesceMs;
     private readonly maxConcurrentMcpRequests;
     private readonly abortController;
@@ -357,10 +464,25 @@ declare class WorkerRemoteDomTransport {
      * to the dispose-level controller.
      */
     private requestSignal;
+    /**
+     * Raises the skew callback the first time this surface is seen to be running against a version
+     * that is no longer installed.
+     *
+     * Latched deliberately. A page typically has several MCP calls in flight, and after an upgrade
+     * every one of them reports the same skew — firing per response would ask the host to remount
+     * the same surface repeatedly, and the second remount would tear down the first. One signal per
+     * transport is all a remount needs, and the transport is discarded along with the surface.
+     *
+     * The callback is host code, so it is assumed to be able to throw. Two consequences are guarded
+     * here: the throw must not escape into the MCP handler's catch (which would reply `ok: false`
+     * for a call that actually succeeded), and it must not consume the latch (which would leave the
+     * surface with no response AND no further chance of being told to remount).
+     */
+    private reportVersionSkew;
     private handleInvokeTool;
     private handleGetResource;
     private handleUploadDocument;
     private replyError;
 }
 
-export { DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, type InputEventPayload as I, type McpHttpClient as M, WORKER_TRANSPORT_PROTOCOL as W, type McpHttpRequest as a, type McpUploadRequest as b, type WorkerCtor as c, type WorkerHandshakePayload as d, type WorkerLike as e, WorkerRemoteDomTransport as f, type WorkerRemoteDomTransportOptions as g };
+export { CAPABILITY_REJECTION_REASON_HEADER as C, DEFAULT_MAX_CONCURRENT_MCP_REQUESTS as D, EXTENSION_ACTIVE_VERSION_HEADER as E, type InputEventPayload as I, type McpHttpClient as M, VERSION_MISMATCH_REASON as V, WORKER_TRANSPORT_PROTOCOL as W, EXTENSION_VERSION_HEADER as a, type McpHttpRequest as b, type McpHttpResponse as c, type McpResponseMetadata as d, type McpUploadRequest as e, type VersionSkew as f, type VersionSkewSource as g, type WorkerCtor as h, type WorkerHandshakePayload as i, type WorkerLike as j, WorkerRemoteDomTransport as k, type WorkerRemoteDomTransportOptions as l, detectVersionSkew as m };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/extension-runtime",
-  "version": "1.58.0",
+  "version": "1.61.0",
   "description": "Host + plugin runtime for EthisysCore Contract A (host-rendered) and Contract B (worker remote-runtime) extensions.",
   "type": "module",
   "main": "./dist/index.cjs",