skedyul 1.2.40 → 1.2.41

package/dist/cli/index.js

@@ -3754,28 +3754,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {

package/dist/dedicated/server.js

@@ -1546,28 +1546,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {

package/dist/esm/index.mjs

@@ -59,14 +59,143 @@ function isRuntimeContext(ctx) {
 // src/types/tool.ts
 import { z } from "zod/v4";
 var ToolResponseMetaSchema = z.object({
-  /** Whether the tool execution succeeded */
   success: z.boolean(),
-  /** Human-readable message describing the result or error */
   message: z.string(),
-  /** Name of the tool that was executed */
   toolName: z.string()
 });
 
+// src/types/tool-response.ts
+function createSuccessResponse(output, options) {
+  return {
+    success: true,
+    output,
+    ...options
+  };
+}
+function createListResponse(items, pagination, options) {
+  return {
+    success: true,
+    output: items,
+    pagination,
+    ...options
+  };
+}
+function inferCategory(code) {
+  switch (code) {
+    case "VALIDATION_ERROR":
+    case "CONFLICT":
+      return "validation";
+    case "AUTH_INVALID":
+    case "AUTH_EXPIRED":
+    case "PERMISSION_DENIED":
+      return "auth";
+    case "TIMEOUT":
+      return "timeout";
+    case "RATE_LIMITED":
+    case "EXTERNAL_SERVICE_ERROR":
+    case "NOT_FOUND":
+    case "QUOTA_EXCEEDED":
+      return "external";
+    default:
+      return "internal";
+  }
+}
+function createErrorResponse(code, message, options) {
+  const category = options?.category ?? inferCategory(code);
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      category,
+      field: options?.field,
+      details: options?.details
+    },
+    retry: options?.retry,
+    partialOutput: options?.partialOutput,
+    billing: options?.billing,
+    effect: options?.effect
+  };
+}
+function createValidationError(message, field, details) {
+  return createErrorResponse("VALIDATION_ERROR", message, {
+    category: "validation",
+    field,
+    details
+  });
+}
+function createNotFoundError(resource2, identifier) {
+  const message = identifier ? `${resource2} '${identifier}' not found` : `${resource2} not found`;
+  return createErrorResponse("NOT_FOUND", message, { category: "external" });
+}
+function createAuthError(message, options) {
+  return createErrorResponse(
+    options?.expired ? "AUTH_EXPIRED" : "AUTH_INVALID",
+    message,
+    { category: "auth", retry: options?.retry }
+  );
+}
+function createRateLimitError(retryAfterMs) {
+  return createErrorResponse(
+    "RATE_LIMITED",
+    "Rate limit exceeded. Please try again later.",
+    {
+      category: "external",
+      retry: {
+        allowed: true,
+        afterMs: retryAfterMs
+      }
+    }
+  );
+}
+function createExternalError(service, message, options) {
+  return createErrorResponse(
+    "EXTERNAL_SERVICE_ERROR",
+    `${service}: ${message}`,
+    {
+      category: "external",
+      retry: options?.retry ?? { allowed: true },
+      details: options?.details
+    }
+  );
+}
+function createTimeoutError(message = "Operation timed out", options) {
+  return createErrorResponse("TIMEOUT", message, {
+    category: "timeout",
+    retry: options?.retry ?? { allowed: true }
+  });
+}
+function createPermissionError(message = "Permission denied") {
+  return createErrorResponse("PERMISSION_DENIED", message, {
+    category: "auth"
+  });
+}
+function createConflictError(message, field) {
+  return createErrorResponse("CONFLICT", message, {
+    category: "validation",
+    field
+  });
+}
+function isSuccess(result) {
+  return result.success === true;
+}
+function isFailure(result) {
+  return result.success === false;
+}
+function isRetryable(result) {
+  if (result.retry?.allowed === false) return false;
+  if (result.retry?.allowed === true) return true;
+  const retryableCategories = [
+    "network",
+    "timeout",
+    "external"
+  ];
+  return result.error.category ? retryableCategories.includes(result.error.category) : false;
+}
+function getRetryDelay(result) {
+  return result.retry?.afterMs;
+}
+
 // src/types/webhook.ts
 function isRuntimeWebhookContext(ctx) {
   return "appInstallationId" in ctx && ctx.appInstallationId !== void 0;
@@ -3272,28 +3401,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure2 = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure2) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {
@@ -3337,7 +3507,7 @@ function createOptionsResponse() {
     body: { message: "OK" }
   };
 }
-function createErrorResponse(err) {
+function createErrorResponse2(err) {
   return {
     status: 500,
     body: {
@@ -3393,7 +3563,7 @@ async function routeRequest(req, ctx) {
     }
     return createNotFoundResponse();
   } catch (err) {
-    return createErrorResponse(err);
+    return createErrorResponse2(err);
   }
 }
 
@@ -4076,9 +4246,20 @@ export {
   ai,
   communicationChannel,
   configure,
+  createAuthError,
+  createConflictError,
   createContextLogger,
+  createErrorResponse,
+  createExternalError,
+  createListResponse,
+  createNotFoundError,
+  createPermissionError,
+  createRateLimitError,
   createServerHookContext,
+  createSuccessResponse,
+  createTimeoutError,
   createToolCallContext,
+  createValidationError,
   createWebhookContext,
   createWorkflowStepContext,
   src_default as default,
@@ -4094,12 +4275,16 @@ export {
   getAllEnvKeys,
   getConfig,
   getRequiredInstallEnvKeys,
+  getRetryDelay,
   instance,
   isChannelDependency,
+  isFailure,
   isModelDependency,
   isProvisionContext,
+  isRetryable,
   isRuntimeContext,
   isRuntimeWebhookContext,
+  isSuccess,
   isWorkflowDependency,
   loadConfig,
   report,

package/dist/index.js

@@ -135,9 +135,20 @@ __export(index_exports, {
   ai: () => ai,
   communicationChannel: () => communicationChannel,
   configure: () => configure,
+  createAuthError: () => createAuthError,
+  createConflictError: () => createConflictError,
   createContextLogger: () => createContextLogger,
+  createErrorResponse: () => createErrorResponse,
+  createExternalError: () => createExternalError,
+  createListResponse: () => createListResponse,
+  createNotFoundError: () => createNotFoundError,
+  createPermissionError: () => createPermissionError,
+  createRateLimitError: () => createRateLimitError,
   createServerHookContext: () => createServerHookContext,
+  createSuccessResponse: () => createSuccessResponse,
+  createTimeoutError: () => createTimeoutError,
   createToolCallContext: () => createToolCallContext,
+  createValidationError: () => createValidationError,
   createWebhookContext: () => createWebhookContext,
   createWorkflowStepContext: () => createWorkflowStepContext,
   default: () => index_default,
@@ -153,12 +164,16 @@ __export(index_exports, {
   getAllEnvKeys: () => getAllEnvKeys,
   getConfig: () => getConfig,
   getRequiredInstallEnvKeys: () => getRequiredInstallEnvKeys,
+  getRetryDelay: () => getRetryDelay,
   instance: () => instance,
   isChannelDependency: () => isChannelDependency,
+  isFailure: () => isFailure,
   isModelDependency: () => isModelDependency,
   isProvisionContext: () => isProvisionContext,
+  isRetryable: () => isRetryable,
   isRuntimeContext: () => isRuntimeContext,
   isRuntimeWebhookContext: () => isRuntimeWebhookContext,
+  isSuccess: () => isSuccess,
   isWorkflowDependency: () => isWorkflowDependency,
   loadConfig: () => loadConfig,
   report: () => report,
@@ -225,14 +240,143 @@ function isRuntimeContext(ctx) {
 // src/types/tool.ts
 var import_v4 = require("zod/v4");
 var ToolResponseMetaSchema = import_v4.z.object({
-  /** Whether the tool execution succeeded */
   success: import_v4.z.boolean(),
-  /** Human-readable message describing the result or error */
   message: import_v4.z.string(),
-  /** Name of the tool that was executed */
   toolName: import_v4.z.string()
 });
 
+// src/types/tool-response.ts
+function createSuccessResponse(output, options) {
+  return {
+    success: true,
+    output,
+    ...options
+  };
+}
+function createListResponse(items, pagination, options) {
+  return {
+    success: true,
+    output: items,
+    pagination,
+    ...options
+  };
+}
+function inferCategory(code) {
+  switch (code) {
+    case "VALIDATION_ERROR":
+    case "CONFLICT":
+      return "validation";
+    case "AUTH_INVALID":
+    case "AUTH_EXPIRED":
+    case "PERMISSION_DENIED":
+      return "auth";
+    case "TIMEOUT":
+      return "timeout";
+    case "RATE_LIMITED":
+    case "EXTERNAL_SERVICE_ERROR":
+    case "NOT_FOUND":
+    case "QUOTA_EXCEEDED":
+      return "external";
+    default:
+      return "internal";
+  }
+}
+function createErrorResponse(code, message, options) {
+  const category = options?.category ?? inferCategory(code);
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      category,
+      field: options?.field,
+      details: options?.details
+    },
+    retry: options?.retry,
+    partialOutput: options?.partialOutput,
+    billing: options?.billing,
+    effect: options?.effect
+  };
+}
+function createValidationError(message, field, details) {
+  return createErrorResponse("VALIDATION_ERROR", message, {
+    category: "validation",
+    field,
+    details
+  });
+}
+function createNotFoundError(resource2, identifier) {
+  const message = identifier ? `${resource2} '${identifier}' not found` : `${resource2} not found`;
+  return createErrorResponse("NOT_FOUND", message, { category: "external" });
+}
+function createAuthError(message, options) {
+  return createErrorResponse(
+    options?.expired ? "AUTH_EXPIRED" : "AUTH_INVALID",
+    message,
+    { category: "auth", retry: options?.retry }
+  );
+}
+function createRateLimitError(retryAfterMs) {
+  return createErrorResponse(
+    "RATE_LIMITED",
+    "Rate limit exceeded. Please try again later.",
+    {
+      category: "external",
+      retry: {
+        allowed: true,
+        afterMs: retryAfterMs
+      }
+    }
+  );
+}
+function createExternalError(service, message, options) {
+  return createErrorResponse(
+    "EXTERNAL_SERVICE_ERROR",
+    `${service}: ${message}`,
+    {
+      category: "external",
+      retry: options?.retry ?? { allowed: true },
+      details: options?.details
+    }
+  );
+}
+function createTimeoutError(message = "Operation timed out", options) {
+  return createErrorResponse("TIMEOUT", message, {
+    category: "timeout",
+    retry: options?.retry ?? { allowed: true }
+  });
+}
+function createPermissionError(message = "Permission denied") {
+  return createErrorResponse("PERMISSION_DENIED", message, {
+    category: "auth"
+  });
+}
+function createConflictError(message, field) {
+  return createErrorResponse("CONFLICT", message, {
+    category: "validation",
+    field
+  });
+}
+function isSuccess(result) {
+  return result.success === true;
+}
+function isFailure(result) {
+  return result.success === false;
+}
+function isRetryable(result) {
+  if (result.retry?.allowed === false) return false;
+  if (result.retry?.allowed === true) return true;
+  const retryableCategories = [
+    "network",
+    "timeout",
+    "external"
+  ];
+  return result.error.category ? retryableCategories.includes(result.error.category) : false;
+}
+function getRetryDelay(result) {
+  return result.retry?.afterMs;
+}
+
 // src/types/webhook.ts
 function isRuntimeWebhookContext(ctx) {
   return "appInstallationId" in ctx && ctx.appInstallationId !== void 0;
@@ -3438,28 +3582,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure2 = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure2) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {
@@ -3503,7 +3688,7 @@ function createOptionsResponse() {
     body: { message: "OK" }
   };
 }
-function createErrorResponse(err) {
+function createErrorResponse2(err) {
   return {
     status: 500,
     body: {
@@ -3559,7 +3744,7 @@ async function routeRequest(req, ctx) {
     }
     return createNotFoundResponse();
   } catch (err) {
-    return createErrorResponse(err);
+    return createErrorResponse2(err);
   }
 }
 
@@ -4243,9 +4428,20 @@ var index_default = { z: import_v44.z };
   ai,
   communicationChannel,
   configure,
+  createAuthError,
+  createConflictError,
   createContextLogger,
+  createErrorResponse,
+  createExternalError,
+  createListResponse,
+  createNotFoundError,
+  createPermissionError,
+  createRateLimitError,
   createServerHookContext,
+  createSuccessResponse,
+  createTimeoutError,
   createToolCallContext,
+  createValidationError,
   createWebhookContext,
   createWorkflowStepContext,
   defineAgent,
@@ -4260,12 +4456,16 @@ var index_default = { z: import_v44.z };
   getAllEnvKeys,
   getConfig,
   getRequiredInstallEnvKeys,
+  getRetryDelay,
   instance,
   isChannelDependency,
+  isFailure,
   isModelDependency,
   isProvisionContext,
+  isRetryable,
   isRuntimeContext,
   isRuntimeWebhookContext,
+  isSuccess,
   isWorkflowDependency,
   loadConfig,
   report,

package/dist/server.js

@@ -1546,28 +1546,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {

package/dist/serverless/server.mjs

@@ -1507,28 +1507,69 @@ async function handleMcpToolsCall(params, id, ctx) {
       invocation: toolInvocation
     });
     let result;
-    if (toolResult.error) {
-      const errorOutput = { error: toolResult.error };
+    const isNewShapeFailure = "success" in toolResult && toolResult.success === false;
+    const isLegacyErrorFailure = "error" in toolResult && toolResult.error != null;
+    const isLegacyMetaFailure = "meta" in toolResult && toolResult.meta != null && typeof toolResult.meta === "object" && "success" in toolResult.meta && toolResult.meta.success === false;
+    const isFailure = isNewShapeFailure || isLegacyErrorFailure || isLegacyMetaFailure;
+    if (isFailure) {
+      let errorOutput;
+      if (isNewShapeFailure && "error" in toolResult) {
+        errorOutput = {
+          error: toolResult.error,
+          retry: "retry" in toolResult ? toolResult.retry : void 0
+        };
+      } else if (isLegacyErrorFailure && "error" in toolResult) {
+        errorOutput = { error: toolResult.error };
+      } else if (isLegacyMetaFailure && "meta" in toolResult && toolResult.meta) {
+        const meta = toolResult.meta;
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: meta.message ?? "Tool execution failed",
+            category: "internal"
+          }
+        };
+      } else {
+        errorOutput = {
+          error: {
+            code: "TOOL_FAILED",
+            message: "Tool execution failed",
+            category: "internal"
+          }
+        };
+      }
       result = {
         content: [{ type: "text", text: JSON.stringify(errorOutput) }],
         structuredContent: hasOutputSchema ? void 0 : errorOutput,
         isError: true,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     } else {
-      const outputData = toolResult.output;
+      const outputData = "output" in toolResult ? toolResult.output : null;
+      const effect = "effect" in toolResult ? toolResult.effect : void 0;
+      const warnings = "warnings" in toolResult ? toolResult.warnings : void 0;
+      const pagination = "pagination" in toolResult ? toolResult.pagination : void 0;
       let structuredContent;
       if (outputData) {
-        structuredContent = { ...outputData, __effect: toolResult.effect };
-      } else if (toolResult.effect) {
-        structuredContent = { __effect: toolResult.effect };
+        structuredContent = {
+          ...outputData,
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
+      } else if (effect || warnings || pagination) {
+        structuredContent = {
+          __effect: effect,
+          __warnings: warnings,
+          __pagination: pagination
+        };
       } else if (hasOutputSchema) {
         structuredContent = {};
       }
       result = {
-        content: [{ type: "text", text: JSON.stringify(toolResult.output) }],
+        content: [{ type: "text", text: JSON.stringify(outputData) }],
         structuredContent,
-        billing: toolResult.billing
+        billing: "billing" in toolResult ? toolResult.billing : void 0
       };
     }
     return {

package/dist/types/index.d.ts

@@ -9,8 +9,9 @@ export type { InvocationType, ServerHookHandle, InvocationContext, } from './inv
 export { createToolCallContext, createServerHookContext, createWebhookContext, createWorkflowStepContext, } from './invocation';
 export type { ToolTrigger, ProvisionToolContext, FieldChangeToolContext, PageActionToolContext, FormSubmitToolContext, AgentToolContext, WorkflowToolContext, ToolExecutionContext, } from './tool-context';
 export { isProvisionContext, isRuntimeContext } from './tool-context';
-export type { BillingInfo, ToolResponseMeta, ToolEffect, ToolError, ToolExecutionResult, ToolSchemaWithJson, ToolSchema, ToolHandler, ToolDefinition, ToolRegistryEntry, ToolRegistry, ToolName, ToolMetadata, ToolCallResponse, } from './tool';
+export type { ToolResult, ToolSuccess, ToolFailure, ErrorCode, ErrorCategory, ToolWarning, ToolPagination, ToolBilling, ToolRetry, ToolTiming, BillingInfo, ToolResponseMeta, ToolEffect, ToolError, ToolExecutionResult, ToolSchemaWithJson, ToolSchema, ToolHandler, ToolDefinition, ToolRegistryEntry, ToolRegistry, ToolName, ToolMetadata, ToolCallResponse, } from './tool';
 export { ToolResponseMetaSchema } from './tool';
+export { createSuccessResponse, createListResponse, createErrorResponse, createValidationError, createNotFoundError, createAuthError, createRateLimitError, createExternalError, createTimeoutError, createPermissionError, createConflictError, isSuccess, isFailure, isRetryable, getRetryDelay, } from './tool-response';
 export type { HealthStatus, ComputeLayer, DedicatedServerInstance, ServerlessServerInstance, SkedyulServerInstance, } from './server';
 export type { InstallHandlerContext, InstallHandlerResponseOAuth, InstallHandlerResponseStandard, HasOAuthCallback, InstallHandlerResult, InstallHandler, UninstallHandlerContext, UninstallHandlerResult, UninstallHandler, OAuthCallbackContext, OAuthCallbackResult, OAuthCallbackHandler, ProvisionHandlerContext, ProvisionHandlerResult, ProvisionHandler, ServerHooksWithOAuth, ServerHooksWithoutOAuth, ServerHooks, } from './handlers';
 export type { APIGatewayProxyEvent, APIGatewayProxyResult } from './aws';

package/dist/types/tool-response.d.ts

@@ -0,0 +1,186 @@
+import type { ToolSuccess, ToolFailure, ToolResult, ErrorCode, ErrorCategory, ToolWarning, ToolPagination, ToolBilling, ToolEffect, ToolRetry } from './tool';
+/**
+ * Create a successful tool result.
+ *
+ * @example
+ * ```ts
+ * import { createSuccessResponse } from 'skedyul'
+ *
+ * return createSuccessResponse({ order: orderData })
+ * ```
+ */
+export declare function createSuccessResponse<T>(output: T, options?: {
+    warnings?: ToolWarning[];
+    pagination?: ToolPagination;
+    billing?: ToolBilling;
+    effect?: ToolEffect;
+}): ToolSuccess<T>;
+/**
+ * Create a successful list response with pagination.
+ *
+ * @example
+ * ```ts
+ * import { createListResponse } from 'skedyul'
+ *
+ * return createListResponse(items, { hasMore: true, total: 100 })
+ * ```
+ */
+export declare function createListResponse<T>(items: T[], pagination: ToolPagination, options?: {
+    warnings?: ToolWarning[];
+    billing?: ToolBilling;
+}): ToolSuccess<T[]>;
+/**
+ * Create a failed tool result with full control over error details.
+ *
+ * @example
+ * ```ts
+ * import { createErrorResponse } from 'skedyul'
+ *
+ * return createErrorResponse('NOT_FOUND', 'Order not found')
+ * ```
+ */
+export declare function createErrorResponse(code: ErrorCode, message: string, options?: {
+    category?: ErrorCategory;
+    field?: string;
+    details?: Record<string, unknown>;
+    retry?: ToolRetry;
+    partialOutput?: unknown;
+    billing?: ToolBilling;
+    effect?: ToolEffect;
+}): ToolFailure;
+/**
+ * Create a validation error result.
+ *
+ * @example
+ * ```ts
+ * import { createValidationError } from 'skedyul'
+ *
+ * return createValidationError('Email is required', 'email')
+ * ```
+ */
+export declare function createValidationError(message: string, field?: string, details?: Record<string, unknown>): ToolFailure;
+/**
+ * Create a not found error result.
+ *
+ * @example
+ * ```ts
+ * import { createNotFoundError } from 'skedyul'
+ *
+ * return createNotFoundError('Order', orderId)
+ * // Error message: "Order 'abc123' not found"
+ * ```
+ */
+export declare function createNotFoundError(resource: string, identifier?: string): ToolFailure;
+/**
+ * Create an authentication error result.
+ *
+ * @example
+ * ```ts
+ * import { createAuthError } from 'skedyul'
+ *
+ * return createAuthError('Invalid API key')
+ * return createAuthError('Token expired', { expired: true })
+ * ```
+ */
+export declare function createAuthError(message: string, options?: {
+    expired?: boolean;
+    retry?: ToolRetry;
+}): ToolFailure;
+/**
+ * Create a rate limit error result.
+ *
+ * @example
+ * ```ts
+ * import { createRateLimitError } from 'skedyul'
+ *
+ * return createRateLimitError(60000) // Retry after 60 seconds
+ * ```
+ */
+export declare function createRateLimitError(retryAfterMs?: number): ToolFailure;
+/**
+ * Create an external service error result.
+ *
+ * @example
+ * ```ts
+ * import { createExternalError } from 'skedyul'
+ *
+ * return createExternalError('Petbooqz API', 'Connection timeout')
+ * ```
+ */
+export declare function createExternalError(service: string, message: string, options?: {
+    retry?: ToolRetry;
+    details?: Record<string, unknown>;
+}): ToolFailure;
+/**
+ * Create a timeout error result.
+ *
+ * @example
+ * ```ts
+ * import { createTimeoutError } from 'skedyul'
+ *
+ * return createTimeoutError('Request timed out after 30 seconds')
+ * ```
+ */
+export declare function createTimeoutError(message?: string, options?: {
+    retry?: ToolRetry;
+}): ToolFailure;
+/**
+ * Create a permission denied error result.
+ *
+ * @example
+ * ```ts
+ * import { createPermissionError } from 'skedyul'
+ *
+ * return createPermissionError('You do not have access to this resource')
+ * ```
+ */
+export declare function createPermissionError(message?: string): ToolFailure;
+/**
+ * Create a conflict error result (e.g., duplicate resource).
+ *
+ * @example
+ * ```ts
+ * import { createConflictError } from 'skedyul'
+ *
+ * return createConflictError('A client with this email already exists')
+ * ```
+ */
+export declare function createConflictError(message: string, field?: string): ToolFailure;
+/**
+ * Type guard to check if a result is successful.
+ *
+ * @example
+ * ```ts
+ * if (isSuccess(result)) {
+ *   console.log(result.output) // TypeScript knows output exists
+ * }
+ * ```
+ */
+export declare function isSuccess<T>(result: ToolResult<T>): result is ToolSuccess<T>;
+/**
+ * Type guard to check if a result is a failure.
+ *
+ * @example
+ * ```ts
+ * if (isFailure(result)) {
+ *   console.log(result.error.code) // TypeScript knows error exists
+ * }
+ * ```
+ */
+export declare function isFailure(result: ToolResult<unknown>): result is ToolFailure;
+/**
+ * Check if an error is retryable based on its category and retry hints.
+ *
+ * @example
+ * ```ts
+ * if (isFailure(result) && isRetryable(result)) {
+ *   // Schedule retry
+ * }
+ * ```
+ */
+export declare function isRetryable(result: ToolFailure): boolean;
+/**
+ * Get the suggested retry delay in milliseconds.
+ * Returns undefined if no retry hint is available.
+ */
+export declare function getRetryDelay(result: ToolFailure): number | undefined;

package/dist/types/tool.d.ts

@@ -5,45 +5,151 @@ import type { ToolExecutionContext } from './tool-context';
  * These tools receive no user input - all data comes from context.
  */
 export type ProvisionToolInput = Record<string, never>;
+/**
+ * Standardized error codes for consistent handling across tools.
+ * Custom codes are allowed for tool-specific errors.
+ */
+export type ErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'AUTH_INVALID' | 'AUTH_EXPIRED' | 'PERMISSION_DENIED' | 'RATE_LIMITED' | 'TIMEOUT' | 'EXTERNAL_SERVICE_ERROR' | 'INTERNAL_ERROR' | 'QUOTA_EXCEEDED' | 'CONFLICT' | string;
+/**
+ * Error category for smart retry logic.
+ * - validation: Don't retry, fix the input
+ * - auth: May need user action (re-login)
+ * - network: Retry with backoff
+ * - timeout: Retry with longer timeout
+ * - external: Retry with backoff
+ * - internal: May retry, but likely a bug
+ */
+export type ErrorCategory = 'validation' | 'auth' | 'network' | 'timeout' | 'external' | 'internal';
+/**
+ * Structured error information with category for smart retry logic.
+ */
+export interface ToolError {
+    code: ErrorCode;
+    message: string;
+    category?: ErrorCategory;
+    field?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Retry guidance for transient failures.
+ */
+export interface ToolRetry {
+    allowed: boolean;
+    afterMs?: number;
+    maxAttempts?: number;
+}
+/**
+ * Non-fatal warning that doesn't prevent success.
+ */
+export interface ToolWarning {
+    code: string;
+    message: string;
+    field?: string;
+}
+/**
+ * Pagination metadata for list operations.
+ */
+export interface ToolPagination {
+    hasMore: boolean;
+    total?: number;
+    nextCursor?: string;
+    page?: number;
+    limit?: number;
+}
+/**
+ * Billing/usage information.
+ */
+export interface ToolBilling {
+    credits: number;
+    tokens?: number;
+    cost?: number;
+}
+/**
+ * Client-side effects to execute after tool completion.
+ */
+export interface ToolEffect {
+    redirect?: string;
+    toast?: {
+        type: 'success' | 'error' | 'warning' | 'info';
+        message: string;
+    };
+    refresh?: string[];
+}
+/**
+ * Execution timing for observability.
+ */
+export interface ToolTiming {
+    durationMs: number;
+}
+/**
+ * Successful tool execution result.
+ * Output is guaranteed to exist.
+ */
+export interface ToolSuccess<T = unknown> {
+    success: true;
+    output: T;
+    warnings?: ToolWarning[];
+    pagination?: ToolPagination;
+    billing?: ToolBilling;
+    effect?: ToolEffect;
+    timing?: ToolTiming;
+}
+/**
+ * Failed tool execution result.
+ * Error is guaranteed to exist, output is not available.
+ */
+export interface ToolFailure {
+    success: false;
+    error: ToolError;
+    retry?: ToolRetry;
+    partialOutput?: unknown;
+    billing?: ToolBilling;
+    effect?: ToolEffect;
+    timing?: ToolTiming;
+}
+/**
+ * Tool execution result - either success or failure.
+ * Use `result.success` to narrow the type.
+ *
+ * @example
+ * ```ts
+ * const result = await tool.handler(input, context)
+ * if (result.success) {
+ *   console.log(result.output) // TypeScript knows output exists
+ * } else {
+ *   console.log(result.error.code) // TypeScript knows error exists
+ * }
+ * ```
+ */
+export type ToolResult<T = unknown> = ToolSuccess<T> | ToolFailure;
+/**
+ * @deprecated Use ToolBilling instead
+ */
 export interface BillingInfo {
     credits: number;
 }
 /**
  * Standardized metadata for tool responses.
- * Provides consistent structure for AI evaluation, logging, and debugging.
+ * @deprecated Use ToolResult discriminated union instead
  */
 export declare const ToolResponseMetaSchema: z.ZodObject<{
     success: z.ZodBoolean;
     message: z.ZodString;
     toolName: z.ZodString;
 }, z.core.$strip>;
-export type ToolResponseMeta = z.infer<typeof ToolResponseMetaSchema>;
 /**
- * Client-side effects that the tool wants the UI to execute.
- * These are separate from the data output and represent navigation/UI actions.
+ * @deprecated Use ToolResult discriminated union instead
  */
-export interface ToolEffect {
-    /** URL to navigate to after the tool completes */
-    redirect?: string;
-}
+export type ToolResponseMeta = z.infer<typeof ToolResponseMetaSchema>;
 /**
- * Structured error information for tool execution results.
- * Uses codes for serialization and workflow detection.
+ * Legacy tool execution result type.
+ * @deprecated Use ToolResult<T> instead. This type is kept for backward compatibility.
  */
-export interface ToolError {
-    code: string;
-    message: string;
-}
 export interface ToolExecutionResult<Output = unknown> {
-    /** Tool-specific output data. Null on error. */
     output: Output | null;
-    /** Billing information */
     billing: BillingInfo;
-    /** Standardized response metadata for AI evaluation and debugging */
     meta: ToolResponseMeta;
-    /** Optional client-side effects to execute */
     effect?: ToolEffect;
-    /** Structured error information (null/undefined if no error) */
     error?: ToolError | null;
 }
 export interface ToolSchemaWithJson<Schema extends z.ZodTypeAny = z.ZodTypeAny> {
@@ -54,8 +160,9 @@ export type ToolSchema<Schema extends z.ZodTypeAny = z.ZodTypeAny> = Schema | To
 /**
  * Tool handler function signature.
  * Receives tool-specific input as first argument and standardized context as second.
+ * Supports both new ToolResult and legacy ToolExecutionResult return types.
  */
-export type ToolHandler<Input, Output> = (input: Input, context: ToolExecutionContext) => Promise<ToolExecutionResult<Output>> | ToolExecutionResult<Output>;
+export type ToolHandler<Input, Output> = (input: Input, context: ToolExecutionContext) => Promise<ToolResult<Output> | ToolExecutionResult<Output>> | ToolResult<Output> | ToolExecutionResult<Output>;
 export interface ToolDefinition<Input = unknown, Output = unknown, InputSchema extends z.ZodTypeAny = z.ZodType<Input>, OutputSchema extends z.ZodTypeAny = z.ZodType<Output>> {
     name: string;
     label?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skedyul",
-  "version": "1.2.40",
+  "version": "1.2.41",
   "description": "The Skedyul SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",