@ethisyscore/plugin-ui 1.71.0 → 1.71.1

package/dist/platform-react/index.d.cts

@@ -154,6 +154,103 @@ declare function useToolInvoker<TReq, TRes>(toolName: string): (req: TReq) => Pr
  */
 declare function useToolInvokerMap(tools: readonly string[]): ToolInvoker;
 
+/**
+ * A single tool's wire contract: the arguments it takes and the payload it returns.
+ *
+ * ## The gap this closes
+ *
+ * `BaseMcpService.tool<TRes>(name: string, args?: unknown)` checks nothing. The tool name is any
+ * string, the arguments are `unknown`, and `TRes` is whatever the caller asserts. Every part of the
+ * boundary is a claim rather than a check, and all three parts have been wrong in production within
+ * a single module:
+ *
+ * - **The result lied.** `tech-list-tool-mappings` returned a bare array while the caller read
+ *   `response.items`, so the table rendered its headers with no rows. No error anywhere.
+ * - **The result lied again.** `tech-auto-match-tool-mappings` returned no payload at all while the
+ *   caller read `response.items.filter(...)`.
+ * - **The arguments were mislabelled.** A service sent `{ connectorId, moduleKey }` where the
+ *   command declared `ConnectorSlug`, so the command rejected every call. Both values were strings,
+ *   so even the service interface it implemented could not catch the swap.
+ *
+ * None of those produced a type error, and none produced a runtime error either - the surface just
+ * quietly did nothing, which is the most expensive failure mode there is.
+ *
+ * ## Phantom, not runtime
+ *
+ * The contract carries no values. `__args` and `__result` exist only so a declaration can name
+ * types; {@link mcpTool} returns a frozen empty object, so both are ABSENT at runtime whatever their
+ * declared types say. Reading one gets `undefined`, never a value to build on - that absence is the
+ * safety property here, not the types themselves.
+ */
+interface McpToolContract<TArgs = unknown, TResult = unknown> {
+    /** Phantom: the arguments this tool accepts. Never present at runtime. */
+    readonly __args: TArgs;
+    /** Phantom: the payload this tool returns. Never present at runtime. */
+    readonly __result: TResult;
+}
+/** A plugin's declared tool surface: tool name to contract. */
+type McpToolContracts = Record<string, McpToolContract>;
+/** The arguments type for one tool in a contract map. */
+type McpToolArgs<TTools extends McpToolContracts, K extends keyof TTools> = TTools[K]["__args"];
+/** The result type for one tool in a contract map. */
+type McpToolResult<TTools extends McpToolContracts, K extends keyof TTools> = TTools[K]["__result"];
+/**
+ * Declares one tool's contract.
+ *
+ * Returns a marker object rather than nothing so the declaration can be a real value: the same
+ * object literal drives the types AND the hook registration (see {@link useTypedToolInvokerMap}),
+ * which is what stops the registered tool list from drifting away from the declared surface.
+ *
+ * @example
+ * export const TOOLS = {
+ *     "tech-list-tool-mappings": mcpTool<{ connectorId: string; moduleKey: string }, MappingsResponse>(),
+ *     "tech-auto-match-tool-mappings": mcpTool<{ connectorId: string }, AutoMatchResponse>(),
+ * } as const;
+ */
+declare function mcpTool<TArgs, TResult>(): McpToolContract<TArgs, TResult>;
+/**
+ * Base class for a service whose tool calls are checked against a declared contract map.
+ *
+ * Deliberately a SEPARATE class from `BaseMcpService` rather than an overload on it. An added
+ * overload would have to keep accepting `(name: string, args?: unknown)` for the services that have
+ * not adopted contracts, and TypeScript would then resolve a mistyped call to that looser signature
+ * instead of rejecting it - so a typo in a tool name would still compile. Opting in by changing base
+ * class means the check cannot be silently bypassed.
+ *
+ * `BaseMcpService` is untouched; nothing has to migrate.
+ *
+ * @example
+ * class ConnectorMappingService extends TypedMcpService<typeof TOOLS> {
+ *     async getMappings(connectorId: string, moduleKey: string) {
+ *         // name, args and result all checked against TOOLS
+ *         return this.tool("tech-list-tool-mappings", { connectorId, moduleKey });
+ *     }
+ * }
+ */
+declare abstract class TypedMcpService<TTools extends McpToolContracts> {
+    private readonly invoker;
+    protected constructor(invoker: ToolInvoker);
+    /**
+     * Invokes a declared tool. The name must be a key of the contract map, the arguments must match
+     * its declared shape, and the result is its declared type - no call-site assertion.
+     */
+    protected tool<K extends keyof TTools & string>(name: K, args: McpToolArgs<TTools, K>): Promise<McpToolResult<TTools, K>>;
+}
+/**
+ * Composes a {@link ToolInvoker} over every tool in a contract declaration.
+ *
+ * Takes the declaration OBJECT, not a list of names, and that is the point: `useToolInvokerMap`
+ * throws `No MCP invoker registered for tool "x"` at runtime when a service calls a tool the list
+ * forgot, and the list and the service were two places to keep in step. Deriving the names from the
+ * contract map makes that drift impossible - if a tool is declared it is registered, and if it is
+ * not declared the call does not typecheck.
+ *
+ * Rules of hooks: pass a module-level `as const` declaration. `Object.keys` on a stable object
+ * yields a stable, constant-length list, which is what the underlying hook requires. Building the
+ * declaration inside a component would vary the hook count between renders and break.
+ */
+declare function useTypedToolInvokerMap<TTools extends McpToolContracts>(contracts: TTools): ToolInvoker;
+
 /**
  * Plugin shim for the monolith's `useAuthenticatedQuery`.
  *
@@ -1207,4 +1304,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type MenuConfigHostSidebarOptions, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.d.ts

@@ -154,6 +154,103 @@ declare function useToolInvoker<TReq, TRes>(toolName: string): (req: TReq) => Pr
  */
 declare function useToolInvokerMap(tools: readonly string[]): ToolInvoker;
 
+/**
+ * A single tool's wire contract: the arguments it takes and the payload it returns.
+ *
+ * ## The gap this closes
+ *
+ * `BaseMcpService.tool<TRes>(name: string, args?: unknown)` checks nothing. The tool name is any
+ * string, the arguments are `unknown`, and `TRes` is whatever the caller asserts. Every part of the
+ * boundary is a claim rather than a check, and all three parts have been wrong in production within
+ * a single module:
+ *
+ * - **The result lied.** `tech-list-tool-mappings` returned a bare array while the caller read
+ *   `response.items`, so the table rendered its headers with no rows. No error anywhere.
+ * - **The result lied again.** `tech-auto-match-tool-mappings` returned no payload at all while the
+ *   caller read `response.items.filter(...)`.
+ * - **The arguments were mislabelled.** A service sent `{ connectorId, moduleKey }` where the
+ *   command declared `ConnectorSlug`, so the command rejected every call. Both values were strings,
+ *   so even the service interface it implemented could not catch the swap.
+ *
+ * None of those produced a type error, and none produced a runtime error either - the surface just
+ * quietly did nothing, which is the most expensive failure mode there is.
+ *
+ * ## Phantom, not runtime
+ *
+ * The contract carries no values. `__args` and `__result` exist only so a declaration can name
+ * types; {@link mcpTool} returns a frozen empty object, so both are ABSENT at runtime whatever their
+ * declared types say. Reading one gets `undefined`, never a value to build on - that absence is the
+ * safety property here, not the types themselves.
+ */
+interface McpToolContract<TArgs = unknown, TResult = unknown> {
+    /** Phantom: the arguments this tool accepts. Never present at runtime. */
+    readonly __args: TArgs;
+    /** Phantom: the payload this tool returns. Never present at runtime. */
+    readonly __result: TResult;
+}
+/** A plugin's declared tool surface: tool name to contract. */
+type McpToolContracts = Record<string, McpToolContract>;
+/** The arguments type for one tool in a contract map. */
+type McpToolArgs<TTools extends McpToolContracts, K extends keyof TTools> = TTools[K]["__args"];
+/** The result type for one tool in a contract map. */
+type McpToolResult<TTools extends McpToolContracts, K extends keyof TTools> = TTools[K]["__result"];
+/**
+ * Declares one tool's contract.
+ *
+ * Returns a marker object rather than nothing so the declaration can be a real value: the same
+ * object literal drives the types AND the hook registration (see {@link useTypedToolInvokerMap}),
+ * which is what stops the registered tool list from drifting away from the declared surface.
+ *
+ * @example
+ * export const TOOLS = {
+ *     "tech-list-tool-mappings": mcpTool<{ connectorId: string; moduleKey: string }, MappingsResponse>(),
+ *     "tech-auto-match-tool-mappings": mcpTool<{ connectorId: string }, AutoMatchResponse>(),
+ * } as const;
+ */
+declare function mcpTool<TArgs, TResult>(): McpToolContract<TArgs, TResult>;
+/**
+ * Base class for a service whose tool calls are checked against a declared contract map.
+ *
+ * Deliberately a SEPARATE class from `BaseMcpService` rather than an overload on it. An added
+ * overload would have to keep accepting `(name: string, args?: unknown)` for the services that have
+ * not adopted contracts, and TypeScript would then resolve a mistyped call to that looser signature
+ * instead of rejecting it - so a typo in a tool name would still compile. Opting in by changing base
+ * class means the check cannot be silently bypassed.
+ *
+ * `BaseMcpService` is untouched; nothing has to migrate.
+ *
+ * @example
+ * class ConnectorMappingService extends TypedMcpService<typeof TOOLS> {
+ *     async getMappings(connectorId: string, moduleKey: string) {
+ *         // name, args and result all checked against TOOLS
+ *         return this.tool("tech-list-tool-mappings", { connectorId, moduleKey });
+ *     }
+ * }
+ */
+declare abstract class TypedMcpService<TTools extends McpToolContracts> {
+    private readonly invoker;
+    protected constructor(invoker: ToolInvoker);
+    /**
+     * Invokes a declared tool. The name must be a key of the contract map, the arguments must match
+     * its declared shape, and the result is its declared type - no call-site assertion.
+     */
+    protected tool<K extends keyof TTools & string>(name: K, args: McpToolArgs<TTools, K>): Promise<McpToolResult<TTools, K>>;
+}
+/**
+ * Composes a {@link ToolInvoker} over every tool in a contract declaration.
+ *
+ * Takes the declaration OBJECT, not a list of names, and that is the point: `useToolInvokerMap`
+ * throws `No MCP invoker registered for tool "x"` at runtime when a service calls a tool the list
+ * forgot, and the list and the service were two places to keep in step. Deriving the names from the
+ * contract map makes that drift impossible - if a tool is declared it is registered, and if it is
+ * not declared the call does not typecheck.
+ *
+ * Rules of hooks: pass a module-level `as const` declaration. `Object.keys` on a stable object
+ * yields a stable, constant-length list, which is what the underlying hook requires. Building the
+ * declaration inside a component would vary the hook count between renders and break.
+ */
+declare function useTypedToolInvokerMap<TTools extends McpToolContracts>(contracts: TTools): ToolInvoker;
+
 /**
  * Plugin shim for the monolith's `useAuthenticatedQuery`.
  *
@@ -1207,4 +1304,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type MenuConfigHostSidebarOptions, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, PluginStyleScope, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, type ToolInvoker, TypedMcpService, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.js

@@ -302,6 +302,26 @@ function useToolInvokerMap(tools) {
     tools.map((t) => invokers[t])
   );
 }
+function mcpTool() {
+  return Object.freeze({});
+}
+var TypedMcpService = class {
+  constructor(invoker) {
+    this.invoker = invoker;
+  }
+  invoker;
+  /**
+   * Invokes a declared tool. The name must be a key of the contract map, the arguments must match
+   * its declared shape, and the result is its declared type - no call-site assertion.
+   */
+  async tool(name, args) {
+    return await this.invoker(name, args);
+  }
+};
+function useTypedToolInvokerMap(contracts) {
+  const names = useMemo(() => Object.freeze(Object.keys(contracts).sort()), [contracts]);
+  return useToolInvokerMap(names);
+}
 function useAuthenticatedQuery(options) {
   const result = useQuery(options);
   return {
@@ -863,6 +883,6 @@ function menuConfigToHostSidebarInput(config, opts) {
   return { mode: "actions", actions };
 }
 
-export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useView };
+export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, MissingViewFallback, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOverlayHost, usePluginRealtime, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map