@ethisyscore/extension-runtime 1.123.0 → 1.124.0

package/dist/plugin/index.d.cts

@@ -1,12 +1,12 @@
-import { M as McpTransport } from '../bridge-envelopes-DAuew-fU.cjs';
-export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-DAuew-fU.cjs';
+import { M as McpTransport } from '../bridge-envelopes-M5a42rAy.cjs';
+export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.cjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
 export { PagedResponse, PaginatedEnvelope } from '@ethisyscore/protocol';
 import { RemoteConnection } from '@remote-dom/core';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-D0fogVGd.cjs';
-export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-D0fogVGd.cjs';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-D9EYFq1l.cjs';
+export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-D9EYFq1l.cjs';
 export { M as MCP_ERROR_CODES, a as McpErrorCode, b as McpToolError, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.cjs';
 
 /**
@@ -230,8 +230,15 @@ interface UseModuleToolResult<TReq, TRes> {
      * Invoke the operation. Each call gets a fresh {@link AbortController} that is
      * aborted on unmount so unresolved promises cannot keep state alive after the
      * component is gone.
+     *
+     * `fallbackReq` is optional and is used ONLY if the declared fallback tool
+     * answers - see {@link McpTransport.invokeOperation}'s `fallbackArgs`. Omit it
+     * and the fallback receives `req`, which is what every call site did before
+     * this parameter existed. It travels beside `req` rather than being fixed on
+     * the hook because the fallback's arguments are normally a rename of the
+     * canonical ones, and those only exist at call time.
      */
-    invoke: (req: TReq) => Promise<TRes>;
+    invoke: (req: TReq, fallbackReq?: unknown) => Promise<TRes>;
     loading: boolean;
     error: Error | undefined;
 }
@@ -252,8 +259,18 @@ interface UseModuleToolResult<TReq, TRes> {
  * call through a per-organisation lookup is the failure that emptied the onboarding
  * admin picker for every SDK-hosted plugin.
  *
+ * **When the fallback tool does not speak canonical.** `invoke(req)` sends `req`
+ * to whichever rung answers. An in-house fallback tool need not declare the
+ * canonical field names, so pass the tool's own shape as the second argument -
+ * `invoke({ personIds }, { employeeIds: personIds })` - and it is used only if
+ * the fallback answers. This is the browser twin of `ModuleFallback`'s second
+ * argument on the backend, and it matters now rather than later: no organisation
+ * has chosen a provider, so the fallback rung is the production path for every
+ * call a conversion makes.
+ *
  * `invoke` is a stable reference across renders for the same module, operation,
- * fallback and transport, making it safe to use inside `useEffect` deps.
+ * fallback and transport, making it safe to use inside `useEffect` deps. The
+ * fallback arguments travel per call and so do not affect that identity.
  */
 declare function useModuleTool<TReq, TRes>(moduleKey: string, operationKey: string, fallbackToolName: string, opts?: UseModuleToolOptions): UseModuleToolResult<TReq, TRes>;
 
@@ -264,6 +281,29 @@ interface UseModuleQueryOptions {
      * violating the rules of hooks. Defaults to `true`.
      */
     enabled?: boolean;
+    /**
+     * Arguments for the FALLBACK rung only, used verbatim in place of `args` when
+     * the declared fallback tool answers. Omit it and the fallback receives
+     * `args`, which is what every call did before this option existed.
+     *
+     * It exists because an in-house fallback tool need not declare the canonical
+     * field names: `hr:get-employee-absences` wants `employeeIds` where the
+     * canonical operation says `personIds`. This is the browser twin of
+     * `ModuleFallback`'s second argument on the backend, and it is load-bearing
+     * today rather than later - no organisation has chosen a provider, so the
+     * fallback rung answers every call a converted read makes.
+     *
+     * It is an option rather than a hook parameter for the same reason `args` is
+     * a parameter here and an `invoke` argument on {@link useModuleTool}: the
+     * fallback's arguments travel wherever the canonical ones travel. Like
+     * `args`, a change to its CONTENTS refetches; a new object with identical
+     * contents does not.
+     *
+     * It carries no authority and cannot change which tool runs. The tool NAME is
+     * still `fallbackToolName`, still checked against the calling extension's
+     * installed manifest by the host before the fallback rung runs.
+     */
+    fallbackArgs?: unknown;
 }
 interface UseModuleQueryResult<TRes> {
     data: TRes | undefined;

package/dist/plugin/index.d.ts

@@ -1,12 +1,12 @@
-import { M as McpTransport } from '../bridge-envelopes-DAuew-fU.js';
-export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-DAuew-fU.js';
+import { M as McpTransport } from '../bridge-envelopes-M5a42rAy.js';
+export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
 export { PagedResponse, PaginatedEnvelope } from '@ethisyscore/protocol';
 import { RemoteConnection } from '@remote-dom/core';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-tIK_iYT9.js';
-export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-tIK_iYT9.js';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-RJOl8WlU.js';
+export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-RJOl8WlU.js';
 export { M as MCP_ERROR_CODES, a as McpErrorCode, b as McpToolError, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.js';
 
 /**
@@ -230,8 +230,15 @@ interface UseModuleToolResult<TReq, TRes> {
      * Invoke the operation. Each call gets a fresh {@link AbortController} that is
      * aborted on unmount so unresolved promises cannot keep state alive after the
      * component is gone.
+     *
+     * `fallbackReq` is optional and is used ONLY if the declared fallback tool
+     * answers - see {@link McpTransport.invokeOperation}'s `fallbackArgs`. Omit it
+     * and the fallback receives `req`, which is what every call site did before
+     * this parameter existed. It travels beside `req` rather than being fixed on
+     * the hook because the fallback's arguments are normally a rename of the
+     * canonical ones, and those only exist at call time.
      */
-    invoke: (req: TReq) => Promise<TRes>;
+    invoke: (req: TReq, fallbackReq?: unknown) => Promise<TRes>;
     loading: boolean;
     error: Error | undefined;
 }
@@ -252,8 +259,18 @@ interface UseModuleToolResult<TReq, TRes> {
  * call through a per-organisation lookup is the failure that emptied the onboarding
  * admin picker for every SDK-hosted plugin.
  *
+ * **When the fallback tool does not speak canonical.** `invoke(req)` sends `req`
+ * to whichever rung answers. An in-house fallback tool need not declare the
+ * canonical field names, so pass the tool's own shape as the second argument -
+ * `invoke({ personIds }, { employeeIds: personIds })` - and it is used only if
+ * the fallback answers. This is the browser twin of `ModuleFallback`'s second
+ * argument on the backend, and it matters now rather than later: no organisation
+ * has chosen a provider, so the fallback rung is the production path for every
+ * call a conversion makes.
+ *
  * `invoke` is a stable reference across renders for the same module, operation,
- * fallback and transport, making it safe to use inside `useEffect` deps.
+ * fallback and transport, making it safe to use inside `useEffect` deps. The
+ * fallback arguments travel per call and so do not affect that identity.
  */
 declare function useModuleTool<TReq, TRes>(moduleKey: string, operationKey: string, fallbackToolName: string, opts?: UseModuleToolOptions): UseModuleToolResult<TReq, TRes>;
 
@@ -264,6 +281,29 @@ interface UseModuleQueryOptions {
      * violating the rules of hooks. Defaults to `true`.
      */
     enabled?: boolean;
+    /**
+     * Arguments for the FALLBACK rung only, used verbatim in place of `args` when
+     * the declared fallback tool answers. Omit it and the fallback receives
+     * `args`, which is what every call did before this option existed.
+     *
+     * It exists because an in-house fallback tool need not declare the canonical
+     * field names: `hr:get-employee-absences` wants `employeeIds` where the
+     * canonical operation says `personIds`. This is the browser twin of
+     * `ModuleFallback`'s second argument on the backend, and it is load-bearing
+     * today rather than later - no organisation has chosen a provider, so the
+     * fallback rung answers every call a converted read makes.
+     *
+     * It is an option rather than a hook parameter for the same reason `args` is
+     * a parameter here and an `invoke` argument on {@link useModuleTool}: the
+     * fallback's arguments travel wherever the canonical ones travel. Like
+     * `args`, a change to its CONTENTS refetches; a new object with identical
+     * contents does not.
+     *
+     * It carries no authority and cannot change which tool runs. The tool NAME is
+     * still `fallbackToolName`, still checked against the calling extension's
+     * installed manifest by the host before the fallback rung runs.
+     */
+    fallbackArgs?: unknown;
 }
 interface UseModuleQueryResult<TRes> {
     data: TRes | undefined;

package/dist/plugin/index.js

@@ -72,7 +72,7 @@ function useModuleTool(moduleKey, operationKey, fallbackToolName, opts) {
     };
   }, []);
   const invoke = useCallback(
-    async (req) => {
+    async (req, fallbackReq) => {
       const controller = new AbortController();
       controllerRef.current?.abort();
       controllerRef.current = controller;
@@ -91,7 +91,8 @@ function useModuleTool(moduleKey, operationKey, fallbackToolName, opts) {
           operationKey,
           fallbackToolName,
           req,
-          controller.signal
+          controller.signal,
+          fallbackReq
         );
         if (mountedRef.current && !controller.signal.aborted) {
           setLoading(false);
@@ -112,12 +113,13 @@ function useModuleTool(moduleKey, operationKey, fallbackToolName, opts) {
 }
 function useModuleQuery(moduleKey, operationKey, fallbackToolName, args, options) {
   const enabled = options?.enabled ?? true;
+  const fallbackArgs = options?.fallbackArgs;
   const { invoke } = useModuleTool(moduleKey, operationKey, fallbackToolName);
   const [data, setData] = useState(void 0);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState(void 0);
   const [tick, setTick] = useState(0);
-  const argsKey = JSON.stringify(args);
+  const argsKey = JSON.stringify([args, fallbackArgs]);
   useEffect(() => {
     if (!enabled) {
       setLoading(false);
@@ -125,7 +127,7 @@ function useModuleQuery(moduleKey, operationKey, fallbackToolName, args, options
     }
     let cancelled = false;
     setLoading(true);
-    invoke(args).then((result) => {
+    invoke(args, fallbackArgs).then((result) => {
       if (cancelled) {
         return;
       }
@@ -731,12 +733,17 @@ function createPortMcpTransport(port, options = {}) {
       const data = await send(WIRE_INVOKE_TOOL_REQUEST, { name, args }, signal);
       return data;
     },
-    async invokeOperation(moduleKey, operationKey, fallbackToolName, args, signal) {
-      const data = await send(
-        WIRE_INVOKE_OPERATION_REQUEST,
-        { moduleKey, operationKey, fallbackToolName, args },
-        signal
-      );
+    async invokeOperation(moduleKey, operationKey, fallbackToolName, args, signal, fallbackArgs) {
+      const body = {
+        moduleKey,
+        operationKey,
+        fallbackToolName,
+        args
+      };
+      if (fallbackArgs !== void 0) {
+        body.fallbackArgs = fallbackArgs;
+      }
+      const data = await send(WIRE_INVOKE_OPERATION_REQUEST, body, signal);
       return data;
     },
     async uploadDocument(meta, buffer, signal) {