fix: toolsHost review updates

Author: cdcabrera

src/__tests__/__snapshots__/server.toolsHost.test.ts.snap

@@ -190,6 +190,74 @@ exports[`requestHello should send hello:ack message, with valid request 1`] = `
 ]
 `;
 
+exports[`requestInvoke should attempt tool invocation, handler attempting to return a DOMException-like object, with name, message and multiline line stack 1`] = `
+{
+  "error": "Internal error",
+  "id": "request-id",
+  "ok": false,
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler attempting to return a browser-like ErrorEvent-like object, with name, message and multiline line stack 1`] = `
+{
+  "error": "Internal error",
+  "id": "request-id",
+  "ok": false,
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler attempting to return an error-like object, with message 1`] = `
+{
+  "id": "request-id",
+  "ok": true,
+  "result": {
+    "message": "Handler error",
+  },
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler attempting to return an error-like object, with name and multiline line stack 1`] = `
+{
+  "error": "Internal error",
+  "id": "request-id",
+  "ok": false,
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler attempting to return an error-like object, with name and single line stack 1`] = `
+{
+  "error": "Internal error",
+  "id": "request-id",
+  "ok": false,
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler attempting to return an error-like object, with single line stack 1`] = `
+{
+  "id": "request-id",
+  "ok": true,
+  "result": {
+    "message": "Handler error",
+    "stack": "Stack trace",
+  },
+  "t": "invoke:result",
+}
+`;
+
+exports[`requestInvoke should attempt tool invocation, handler returning AggregateError 1`] = `
+{
+  "error": "Internal error",
+  "id": "request-id",
+  "ok": false,
+  "t": "invoke:result",
+}
+`;
+
 exports[`requestInvoke should attempt tool invocation, handler returning error 1`] = `
 {
   "error": "Internal error",
@@ -199,6 +267,15 @@ exports[`requestInvoke should attempt tool invocation, handler returning error 1
 }
 `;
 
+exports[`requestInvoke should attempt tool invocation, handler returning null 1`] = `
+{
+  "id": "request-id",
+  "ok": true,
+  "result": null,
+  "t": "invoke:result",
+}
+`;
+
 exports[`requestInvoke should attempt tool invocation, handler returning promise 1`] = `
 {
   "id": "request-id",
@@ -210,6 +287,15 @@ exports[`requestInvoke should attempt tool invocation, handler returning promise
 }
 `;
 
+exports[`requestInvoke should attempt tool invocation, handler returning undefined 1`] = `
+{
+  "id": "request-id",
+  "ok": true,
+  "result": undefined,
+  "t": "invoke:result",
+}
+`;
+
 exports[`requestInvoke should attempt tool invocation, handler throwing error 1`] = `
 {
   "error": "Handler error",

src/__tests__/server.toolsHost.test.ts

@@ -183,6 +183,60 @@ describe('requestInvoke', () => {
       handlerResult: { data: 'result' },
       stateToolId: 'tool-1',
       requestToolId: 'tool-2'
+    },
+    {
+      description: 'handler returning AggregateError',
+      handlerResult: new AggregateError(['Handler error']),
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return an error-like object, with message',
+      handlerResult: { message: 'Handler error' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return an error-like object, with single line stack',
+      handlerResult: { message: 'Handler error', stack: 'Stack trace' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return an error-like object, with name and single line stack',
+      handlerResult: { name: 'Mock ERROR', message: 'Handler error', stack: 'Stack trace' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return an error-like object, with name and multiline line stack',
+      handlerResult: { name: 'Mock', message: 'Handler error', stack: 'Stack trace\nSecond line' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return a DOMException-like object, with name, message and multiline line stack',
+      handlerResult: { name: 'DOMException', message: 'Handler error', stack: 'DOMException: message\n at line x' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler attempting to return a browser-like ErrorEvent-like object, with name, message and multiline line stack',
+      handlerResult: { name: 'ErrorEvent', message: 'Handler error', stack: 'ErrorEvent: message\n at line x' },
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler returning undefined',
+      handlerResult: undefined,
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
+    },
+    {
+      description: 'handler returning null',
+      handlerResult: null,
+      stateToolId: 'tool-1',
+      requestToolId: 'tool-1'
     }
   ])('should attempt tool invocation, $description', async ({ handlerResult, stateToolId, requestToolId }) => {
     const mockState = {

src/server.toolsHost.ts

@@ -95,6 +95,45 @@ type NormalizeCreatorSchemaResult = {
   warnings: string[];
 };
 
+/**
+ * Check if a value is an error or an error-like object.
+ *
+ * Handles cross‑realm Error detection via tag checks for `[object Error]`, `[object AggregateError]`,
+ * and `[object DOMException]`. Does not treat `[object ErrorEvent]` as error‑like in the
+ * Node context; add if your runtime can emit `ErrorEvent`.
+ *
+ * @param value
+ * @returns True if the value is an error-like object, false otherwise.
+ */
+const isErrorLike = (value: unknown) => {
+  if (!value || (typeof value !== 'object' && typeof value !== 'function')) {
+    return false;
+  }
+
+  if (value instanceof Error || value instanceof AggregateError) {
+    return true;
+  }
+
+  const tag = Object.prototype.toString.call(value);
+
+  if (tag === '[object Error]' || tag === '[object AggregateError]' || tag === '[object DOMException]') {
+    return true;
+  }
+
+  const val = value as Record<string, unknown>;
+  const has = (key: string) =>
+    Object.hasOwn(val, key) && typeof val[key] === 'string' && val[key].length > 0;
+
+  if (!has('message')) {
+    return false;
+  }
+
+  const isNameLike = has('name') && (val.name as string).toLowerCase().endsWith('error');
+  const isStackLike = has('stack') && (val.stack as string).includes('\n');
+
+  return isNameLike || isStackLike;
+};
+
 /**
  * Normalize a tool creator function and its input schema.
  *
@@ -325,7 +364,8 @@ const requestInvoke = async (state: HostState, request: InvokeRequest) => {
     // Invoke the tool
     const result = await Promise.resolve(handler(updatedRequestArgs));
 
-    if (result instanceof Error) {
+    // Some handlers may mistakenly return an Error instance instead of throwing. Normalize it to a failure.
+    if (isErrorLike(result)) {
       const err: SerializedError = new Error('Internal error', { cause: { details: result } });
 
       err.code = 'INTERNAL_ERROR';