skedyul 1.2.40 → 1.2.43

package/dist/types/index.d.ts

@@ -9,11 +9,13 @@ 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, ToolCompletionHints, ToolConfig, 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';
 export type { WebhookWireRequest, HandlerRawRequest, WebhookRequest, WebhookResponse, ProvisionWebhookContext, RuntimeWebhookContext, WebhookContext, WebhookHandler, WebhookLifecycleContext, CommunicationChannelLifecycleContext, WebhookLifecycleResult, WebhookLifecycleHook, WebhookInvocationMode, WebhookType, WebhookDefinition, WebhookRegistry, WebhookName, WebhookMetadata, } from './webhook';
 export { isRuntimeWebhookContext } from './webhook';
 export type { MCPError, MCPContentItem, MCPResult, MCPResponse, MCPRequest, } from './mcp-protocol';
+export type { DataBlock, DataBlockLink, SpreadsheetBlock, SpreadsheetColumn, ProfileBlock, ProfileAvatar, ProfileField, FieldChangesBlock, FieldChangeItem, DateTimeBlock, } from './data-blocks';

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

@@ -0,0 +1,202 @@
+import type { ToolSuccess, ToolFailure, ToolResult, ErrorCode, ErrorCategory, ToolWarning, ToolPagination, ToolBilling, ToolEffect, ToolRetry } from './tool';
+import type { DataBlock } from './data-blocks';
+/**
+ * Create a successful tool result.
+ *
+ * @example
+ * ```ts
+ * import { createSuccessResponse } from 'skedyul'
+ *
+ * return createSuccessResponse({ order: orderData })
+ *
+ * // With dataBlocks for rich UI rendering
+ * return createSuccessResponse(
+ *   { booking: bookingData },
+ *   {
+ *     dataBlocks: [{
+ *       type: 'dateTime',
+ *       title: 'Booking Confirmed',
+ *       datetime: '2026-05-20T14:00:00',
+ *       status: 'confirmed',
+ *     }]
+ *   }
+ * )
+ * ```
+ */
+export declare function createSuccessResponse<T>(output: T, options?: {
+    /** Rich data blocks for UI rendering (profiles, spreadsheets, datetime cards) */
+    dataBlocks?: DataBlock[];
+    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,175 @@ 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;
+}
+/**
+ * Hints for controlling tool completion behavior in agent loops.
+ * Used to prevent duplicate calls and determine when to stop tool execution.
+ */
+export interface ToolCompletionHints {
+    /** Maximum times this tool can be called per agent run. Default: unlimited */
+    maxCallsPerRun?: number;
+    /** If true, tool is safe to call multiple times with same args (no side effects) */
+    idempotent?: boolean;
+}
+/**
+ * Configuration options for tool execution behavior.
+ * Groups timeout, retry, and completion hint settings.
+ */
+export interface ToolConfig {
+    /** Timeout in milliseconds. Defaults to 10000 (10 seconds) if not specified. */
+    timeout?: number;
+    /** Maximum retry attempts. Defaults to 1 (no retries) if not specified. */
+    retries?: number;
+    /** Hints for controlling tool completion behavior in agent loops */
+    completionHints?: ToolCompletionHints;
+}
+/**
+ * Successful tool execution result.
+ * Output is guaranteed to exist.
+ */
+export interface ToolSuccess<T = unknown> {
+    success: true;
+    output: T;
+    /** Rich data blocks for UI rendering (profiles, spreadsheets, datetime cards) */
+    dataBlocks?: import('./data-blocks').DataBlock[];
+    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 +184,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;
@@ -63,10 +194,8 @@ export interface ToolDefinition<Input = unknown, Output = unknown, InputSchema e
     inputSchema: ToolSchema<InputSchema>;
     handler: ToolHandler<Input, Output>;
     outputSchema?: ToolSchema<OutputSchema>;
-    /** Timeout in milliseconds. Defaults to 10000 (10 seconds) if not specified. */
-    timeout?: number;
-    /** Maximum retry attempts. Defaults to 1 (no retries) if not specified. */
-    retries?: number;
+    /** Tool execution configuration (timeout, retries, completion hints) */
+    config?: ToolConfig;
     [key: string]: unknown;
 }
 export interface ToolRegistryEntry {
@@ -76,6 +205,8 @@ export interface ToolRegistryEntry {
     inputSchema: ToolSchema;
     handler: unknown;
     outputSchema?: ToolSchema;
+    /** Tool execution configuration (timeout, retries, completion hints) */
+    config?: ToolConfig;
     [key: string]: unknown;
 }
 export type ToolRegistry = Record<string, ToolRegistryEntry>;
@@ -86,10 +217,8 @@ export interface ToolMetadata {
     description: string;
     inputSchema?: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
-    /** Timeout in milliseconds. Defaults to 10000 (10 seconds) if not specified. */
-    timeout?: number;
-    /** Maximum retry attempts. Defaults to 1 (no retries) if not specified. */
-    retries?: number;
+    /** Tool execution configuration (timeout, retries, completion hints) */
+    config?: ToolConfig;
 }
 /**
  * Response from a tool call.

package/dist/workflows/index.d.ts

@@ -0,0 +1 @@
+export { WORKFLOW_SCHEMA_VERSION, WorkflowInputSchema, WorkflowStepInputSchema, WorkflowStepSchema, WorkflowRuntimeSchema, WorkflowYAMLSchema, WorkflowMetadataSchema, WorkflowExecutionStatusSchema, WorkflowExecutionResultSchema, type WorkflowInput, type WorkflowStepInput, type WorkflowStep, type WorkflowRuntime, type WorkflowYAML, type WorkflowMetadata, type WorkflowExecutionStatus, type WorkflowExecutionResult, defineWorkflowYAML, validateWorkflowYAML, } from './types';