byterover-cli 1.2.0 → 1.3.0

package/dist/core/domain/transport/schemas.d.ts

@@ -34,12 +34,12 @@ export declare const TodoItemSchema: z.ZodObject<{
     status: z.ZodEnum<["cancelled", "completed", "in_progress", "pending"]>;
 }, "strip", z.ZodTypeAny, {
     status: "cancelled" | "completed" | "in_progress" | "pending";
-    activeForm: string;
     content: string;
+    activeForm: string;
 }, {
     status: "cancelled" | "completed" | "in_progress" | "pending";
-    activeForm: string;
     content: string;
+    activeForm: string;
 }>;
 export declare const ConversationResetPayloadSchema: z.ZodObject<{
     sessionId: z.ZodString;
@@ -54,14 +54,14 @@ export declare const ExecutionStartedPayloadSchema: z.ZodObject<{
     sessionId: z.ZodString;
     startTime: z.ZodDate;
 }, "strip", z.ZodTypeAny, {
-    sessionId: string;
     maxIterations: number;
     startTime: Date;
+    sessionId: string;
     maxTimeMs?: number | undefined;
 }, {
-    sessionId: string;
     maxIterations: number;
     startTime: Date;
+    sessionId: string;
     maxTimeMs?: number | undefined;
 }>;
 export declare const ExecutionTerminatedPayloadSchema: z.ZodObject<{
@@ -73,19 +73,19 @@ export declare const ExecutionTerminatedPayloadSchema: z.ZodObject<{
     toolCallsExecuted: z.ZodNumber;
     turnCount: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    sessionId: string;
-    endTime: Date;
-    reason: "TIMEOUT" | "ABORTED" | "ERROR" | "GOAL" | "MAX_TURNS" | "PROTOCOL_VIOLATION";
     toolCallsExecuted: number;
     turnCount: number;
+    reason: "ABORTED" | "ERROR" | "GOAL" | "MAX_TURNS" | "PROTOCOL_VIOLATION" | "TIMEOUT";
+    sessionId: string;
+    endTime: Date;
     error?: any;
     durationMs?: number | undefined;
 }, {
-    sessionId: string;
-    endTime: Date;
-    reason: "TIMEOUT" | "ABORTED" | "ERROR" | "GOAL" | "MAX_TURNS" | "PROTOCOL_VIOLATION";
     toolCallsExecuted: number;
     turnCount: number;
+    reason: "ABORTED" | "ERROR" | "GOAL" | "MAX_TURNS" | "PROTOCOL_VIOLATION" | "TIMEOUT";
+    sessionId: string;
+    endTime: Date;
     error?: any;
     durationMs?: number | undefined;
 }>;
@@ -98,14 +98,14 @@ export declare const LogPayloadSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     message: string;
     level: "debug" | "error" | "info" | "warn";
-    source?: string | undefined;
     sessionId?: string | undefined;
+    source?: string | undefined;
     context?: Record<string, unknown> | undefined;
 }, {
     message: string;
     level: "debug" | "error" | "info" | "warn";
-    source?: string | undefined;
     sessionId?: string | undefined;
+    source?: string | undefined;
     context?: Record<string, unknown> | undefined;
 }>;
 export declare const StateChangedPayloadSchema: z.ZodObject<{
@@ -137,12 +137,12 @@ export declare const UIPayloadSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<["banner", "help", "prompt", "response", "separator", "shutdown"]>;
 }, "strip", z.ZodTypeAny, {
-    type: "banner" | "help" | "prompt" | "response" | "separator" | "shutdown";
+    type: "prompt" | "banner" | "help" | "response" | "separator" | "shutdown";
     message?: string | undefined;
     sessionId?: string | undefined;
     context?: Record<string, unknown> | undefined;
 }, {
-    type: "banner" | "help" | "prompt" | "response" | "separator" | "shutdown";
+    type: "prompt" | "banner" | "help" | "response" | "separator" | "shutdown";
     message?: string | undefined;
     sessionId?: string | undefined;
     context?: Record<string, unknown> | undefined;
@@ -154,13 +154,13 @@ export declare const ChunkPayloadSchema: z.ZodObject<{
     type: z.ZodEnum<["reasoning", "text"]>;
 }, "strip", z.ZodTypeAny, {
     type: "reasoning" | "text";
-    content: string;
     sessionId: string;
+    content: string;
     isComplete?: boolean | undefined;
 }, {
     type: "reasoning" | "text";
-    content: string;
     sessionId: string;
+    content: string;
     isComplete?: boolean | undefined;
 }>;
 export declare const ErrorPayloadSchema: z.ZodObject<{
@@ -183,14 +183,14 @@ export declare const OutputTruncatedPayloadSchema: z.ZodObject<{
     toolName: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
+    toolName: string;
     originalLength: number;
     savedToFile: string;
-    toolName: string;
 }, {
     sessionId: string;
+    toolName: string;
     originalLength: number;
     savedToFile: string;
-    toolName: string;
 }>;
 export declare const ResponsePayloadSchema: z.ZodObject<{
     content: z.ZodString;
@@ -213,24 +213,24 @@ export declare const ResponsePayloadSchema: z.ZodObject<{
         totalTokens: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    content: string;
     sessionId: string;
-    reasoning?: string | undefined;
+    content: string;
     model?: string | undefined;
-    partial?: boolean | undefined;
+    reasoning?: string | undefined;
     provider?: string | undefined;
+    partial?: boolean | undefined;
     tokenUsage?: {
         inputTokens: number;
         outputTokens: number;
         totalTokens: number;
     } | undefined;
 }, {
-    content: string;
     sessionId: string;
-    reasoning?: string | undefined;
+    content: string;
     model?: string | undefined;
-    partial?: boolean | undefined;
+    reasoning?: string | undefined;
     provider?: string | undefined;
+    partial?: boolean | undefined;
     tokenUsage?: {
         inputTokens: number;
         outputTokens: number;
@@ -249,12 +249,12 @@ export declare const ThoughtPayloadSchema: z.ZodObject<{
     sessionId: z.ZodString;
     subject: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    sessionId: string;
     description: string;
+    sessionId: string;
     subject: string;
 }, {
-    sessionId: string;
     description: string;
+    sessionId: string;
     subject: string;
 }>;
 export declare const TodoUpdatedPayloadSchema: z.ZodObject<{
@@ -265,26 +265,26 @@ export declare const TodoUpdatedPayloadSchema: z.ZodObject<{
         status: z.ZodEnum<["cancelled", "completed", "in_progress", "pending"]>;
     }, "strip", z.ZodTypeAny, {
         status: "cancelled" | "completed" | "in_progress" | "pending";
-        activeForm: string;
         content: string;
+        activeForm: string;
     }, {
         status: "cancelled" | "completed" | "in_progress" | "pending";
-        activeForm: string;
         content: string;
+        activeForm: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
     todos: {
         status: "cancelled" | "completed" | "in_progress" | "pending";
-        activeForm: string;
         content: string;
+        activeForm: string;
     }[];
 }, {
     sessionId: string;
     todos: {
         status: "cancelled" | "completed" | "in_progress" | "pending";
-        activeForm: string;
         content: string;
+        activeForm: string;
     }[];
 }>;
 export declare const ToolCallPayloadSchema: z.ZodObject<{
@@ -318,8 +318,8 @@ export declare const ToolResultPayloadSchema: z.ZodObject<{
     success: boolean;
     error?: string | undefined;
     callId?: string | undefined;
-    errorType?: "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TIMEOUT" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     metadata?: Record<string, unknown> | undefined;
+    errorType?: "TIMEOUT" | "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     result?: unknown;
 }, {
     sessionId: string;
@@ -327,19 +327,19 @@ export declare const ToolResultPayloadSchema: z.ZodObject<{
     success: boolean;
     error?: string | undefined;
     callId?: string | undefined;
-    errorType?: "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TIMEOUT" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     metadata?: Record<string, unknown> | undefined;
+    errorType?: "TIMEOUT" | "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     result?: unknown;
 }>;
 export declare const UnsupportedInputPayloadSchema: z.ZodObject<{
     reason: z.ZodString;
     sessionId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    sessionId: string;
     reason: string;
-}, {
     sessionId: string;
+}, {
     reason: string;
+    sessionId: string;
 }>;
 export declare const WarningPayloadSchema: z.ZodObject<{
     message: z.ZodString;
@@ -464,19 +464,19 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     /** Task type */
     type: z.ZodEnum<["curate", "query"]>;
 }, "strip", z.ZodTypeAny, {
+    clientId: string;
     type: "curate" | "query";
     content: string;
-    clientId: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }, {
+    clientId: string;
     type: "curate" | "query";
     content: string;
-    clientId: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }>;
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -557,14 +557,14 @@ export declare const LlmChunkEventSchema: z.ZodObject<{
     type: z.ZodEnum<["reasoning", "text"]>;
 }, "strip", z.ZodTypeAny, {
     type: "reasoning" | "text";
-    content: string;
     sessionId: string;
+    content: string;
     taskId: string;
     isComplete?: boolean | undefined;
 }, {
     type: "reasoning" | "text";
-    content: string;
     sessionId: string;
+    content: string;
     taskId: string;
     isComplete?: boolean | undefined;
 }>;
@@ -589,12 +589,12 @@ export declare const LlmUnsupportedInputEventSchema: z.ZodObject<{
     sessionId: z.ZodString;
     taskId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    sessionId: string;
     reason: string;
+    sessionId: string;
     taskId: string;
 }, {
-    sessionId: string;
     reason: string;
+    sessionId: string;
     taskId: string;
 }>;
 /**
@@ -626,14 +626,14 @@ export declare const TaskCreatedSchema: z.ZodObject<{
     type: "curate" | "query";
     content: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }, {
     type: "curate" | "query";
     content: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }>;
 /**
  * task:started - Agent begins processing the task
@@ -655,14 +655,14 @@ export declare const TaskStartedEventSchema: z.ZodObject<{
     taskId: string;
     type?: string | undefined;
     content?: string | undefined;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }, {
     taskId: string;
     type?: string | undefined;
     content?: string | undefined;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }>;
 /**
  * task:cancelled - Task was cancelled before completion
@@ -772,26 +772,26 @@ export declare const LlmResponseEventSchema: z.ZodObject<{
         totalTokens: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    content: string;
     sessionId: string;
+    content: string;
     taskId: string;
-    reasoning?: string | undefined;
     model?: string | undefined;
-    partial?: boolean | undefined;
+    reasoning?: string | undefined;
     provider?: string | undefined;
+    partial?: boolean | undefined;
     tokenUsage?: {
         inputTokens: number;
         outputTokens: number;
         totalTokens: number;
     } | undefined;
 }, {
-    content: string;
     sessionId: string;
+    content: string;
     taskId: string;
-    reasoning?: string | undefined;
     model?: string | undefined;
-    partial?: boolean | undefined;
+    reasoning?: string | undefined;
     provider?: string | undefined;
+    partial?: boolean | undefined;
     tokenUsage?: {
         inputTokens: number;
         outputTokens: number;
@@ -842,8 +842,8 @@ export declare const LlmToolResultEventSchema: z.ZodObject<{
     taskId: string;
     error?: string | undefined;
     callId?: string | undefined;
-    errorType?: "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TIMEOUT" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     metadata?: Record<string, unknown> | undefined;
+    errorType?: "TIMEOUT" | "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     result?: unknown;
 }, {
     sessionId: string;
@@ -852,8 +852,8 @@ export declare const LlmToolResultEventSchema: z.ZodObject<{
     taskId: string;
     error?: string | undefined;
     callId?: string | undefined;
-    errorType?: "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TIMEOUT" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     metadata?: Record<string, unknown> | undefined;
+    errorType?: "TIMEOUT" | "CANCELLED" | "CONFIRMATION_REJECTED" | "EXECUTION_FAILED" | "INTERNAL_ERROR" | "INVALID_PARAM_TYPE" | "INVALID_PARAMS" | "MISSING_REQUIRED_PARAM" | "PARAM_VALIDATION_FAILED" | "PERMISSION_DENIED" | "PROVIDER_ERROR" | "TOOL_DISABLED" | "TOOL_NOT_FOUND" | undefined;
     result?: unknown;
 }>;
 export type TaskAck = z.infer<typeof TaskAckSchema>;
@@ -882,14 +882,14 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     type: "curate" | "query";
     content: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }, {
     type: "curate" | "query";
     content: string;
     taskId: string;
-    clientCwd?: string | undefined;
     files?: string[] | undefined;
+    clientCwd?: string | undefined;
 }>;
 /**
  * Response after task creation
@@ -935,13 +935,13 @@ export declare const SessionInfoSchema: z.ZodObject<{
     lastActiveAt: z.ZodNumber;
     name: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    createdAt: number;
     id: string;
+    createdAt: number;
     lastActiveAt: number;
     name?: string | undefined;
 }, {
-    createdAt: number;
     id: string;
+    createdAt: number;
     lastActiveAt: number;
     name?: string | undefined;
 }>;
@@ -975,13 +975,13 @@ export declare const SessionInfoResponseSchema: z.ZodObject<{
         lastActiveAt: z.ZodNumber;
         name: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }, {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }>;
@@ -1000,8 +1000,8 @@ export declare const SessionInfoResponseSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     session: {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     };
@@ -1012,8 +1012,8 @@ export declare const SessionInfoResponseSchema: z.ZodObject<{
     };
 }, {
     session: {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     };
@@ -1037,27 +1037,27 @@ export declare const SessionListResponseSchema: z.ZodObject<{
         lastActiveAt: z.ZodNumber;
         name: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }, {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     sessions: {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }[];
 }, {
     sessions: {
-        createdAt: number;
         id: string;
+        createdAt: number;
         lastActiveAt: number;
         name?: string | undefined;
     }[];

package/dist/core/interfaces/cipher/i-chat-session.d.ts

@@ -56,13 +56,15 @@ export interface IChatSession {
      * @param input - User message content
      * @param options - Optional execution options
      * @param options.executionContext - Optional execution context
-     * @param options.taskId - Optional task ID for concurrent task isolation (included in all emitted events)
+     * @param options.taskId - Optional task ID for billing tracking and event correlation
+     * @param options.emitTaskId - Whether to include taskId in emitted events (default: true)
      * @returns Assistant response
      * @throws SessionCancelledError if operation is cancelled
      * @throws MaxIterationsExceededError if tool loop exceeds maximum iterations
      * @throws LLMError if LLM call fails
      */
     run(input: string, options?: {
+        emitTaskId?: boolean;
         executionContext?: ExecutionContext;
         taskId?: string;
     }): Promise<string>;

package/dist/core/interfaces/connectors/i-connector.d.ts

@@ -6,6 +6,8 @@ import type { ConnectorInstallResult, ConnectorStatus, ConnectorUninstallResult
  * Each connector type (rules, hook, mcp) has its own implementation.
  */
 export interface IConnector {
+    /** The type of this connector */
+    readonly connectorType: ConnectorType;
     /**
      * Get the path to the configuration/rule file for a specific agent.
      *
@@ -41,8 +43,6 @@ export interface IConnector {
      * @returns Status including installed state and config file existence
      */
     status(agent: Agent): Promise<ConnectorStatus>;
-    /** The type of this connector */
-    readonly type: ConnectorType;
     /**
      * Uninstall the connector for the specified agent.
      * Only removes BRV content, preserves user's other configurations.

package/dist/core/interfaces/i-file-service.d.ts

@@ -22,6 +22,13 @@ export interface IFileService {
      * @returns A promise that resolves when the file has been deleted.
      */
     delete: (filePath: string) => Promise<void>;
+    /**
+     * Deletes a directory and all its contents recursively.
+     *
+     * @param dirPath The path to the directory to delete.
+     * @returns A promise that resolves when the directory has been deleted.
+     */
+    deleteDirectory: (dirPath: string) => Promise<void>;
     /**
      * Checks if a file exists at the specified path.
      *

package/dist/infra/auth/oauth-service.d.ts

@@ -1,6 +1,15 @@
 import { OAuthConfig } from '../../config/auth.config.js';
 import { OAuthTokenData } from '../../core/domain/entities/oauth-token-data.js';
 import { AuthorizationContext, IAuthService } from '../../core/interfaces/i-auth-service.js';
+export declare const NETWORK_ERROR_CODE: {
+    readonly EAI_AGAIN: "EAI_AGAIN";
+    readonly ECONNABORTED: "ECONNABORTED";
+    readonly ECONNREFUSED: "ECONNREFUSED";
+    readonly ECONNRESET: "ECONNRESET";
+    readonly ENOTFOUND: "ENOTFOUND";
+    readonly ERR_NETWORK: "ERR_NETWORK";
+    readonly ETIMEDOUT: "ETIMEDOUT";
+};
 /**
  * OAuth service implementation for handling OAuth authentication flows.
  */
@@ -40,6 +49,12 @@ export declare class OAuthService implements IAuthService {
      * @returns A random state string.
      */
     private generateState;
+    /**
+     * Returns a user-friendly error message for network-related errors.
+     * @param errorCode The Axios error code (e.g., ECONNREFUSED, ETIMEOUT, etc.).
+     * @returns A user-friendly error message.
+     */
+    private getNetworkErrorMessage;
     /**
      * Parses the token response from the OAuth server.
      * @param data The response data from the OAuth server.

package/dist/infra/auth/oauth-service.js

@@ -3,6 +3,15 @@ import axios, { isAxiosError } from 'axios';
 import crypto from 'node:crypto';
 import { OAuthTokenData } from '../../core/domain/entities/oauth-token-data.js';
 import { AuthenticationError } from '../../core/domain/errors/auth-error.js';
+export const NETWORK_ERROR_CODE = {
+    EAI_AGAIN: 'EAI_AGAIN',
+    ECONNABORTED: 'ECONNABORTED',
+    ECONNREFUSED: 'ECONNREFUSED',
+    ECONNRESET: 'ECONNRESET',
+    ENOTFOUND: 'ENOTFOUND',
+    ERR_NETWORK: 'ERR_NETWORK',
+    ETIMEDOUT: 'ETIMEDOUT'
+};
 /**
  * OAuth service implementation for handling OAuth authentication flows.
  */
@@ -45,7 +54,7 @@ export class OAuthService {
         }
         catch (error) {
             if (isAxiosError(error)) {
-                throw new AuthenticationError(error.response?.data?.error_description ?? 'Failed to exchange code for token', error.response?.data?.error);
+                throw new AuthenticationError(error.response?.data?.error_description ?? this.getNetworkErrorMessage(error.code), error.response?.data?.error ?? error.code);
             }
             throw error;
         }
@@ -87,7 +96,7 @@ export class OAuthService {
         }
         catch (error) {
             if (isAxiosError(error)) {
-                throw new AuthenticationError(error.response?.data?.error_description ?? 'Failed to refresh token', error.response?.data?.error);
+                throw new AuthenticationError(error.response?.data?.error_description ?? this.getNetworkErrorMessage(error.code), error.response?.data?.error ?? error.code);
             }
             throw error;
         }
@@ -114,6 +123,33 @@ export class OAuthService {
     generateState() {
         return crypto.randomBytes(16).toString('base64url');
     }
+    /**
+     * Returns a user-friendly error message for network-related errors.
+     * @param errorCode The Axios error code (e.g., ECONNREFUSED, ETIMEOUT, etc.).
+     * @returns A user-friendly error message.
+     */
+    getNetworkErrorMessage(errorCode) {
+        switch (errorCode) {
+            case NETWORK_ERROR_CODE.EAI_AGAIN:
+            case NETWORK_ERROR_CODE.ENOTFOUND: {
+                return 'Unable to reach authentication server. Please check your internet connection.';
+            }
+            case NETWORK_ERROR_CODE.ECONNABORTED:
+            case NETWORK_ERROR_CODE.ETIMEDOUT: {
+                return 'Login timed out. Please check your internet connection and try again.';
+            }
+            case NETWORK_ERROR_CODE.ECONNREFUSED:
+            case NETWORK_ERROR_CODE.ECONNRESET: {
+                return 'Unable to reach authentication server. Please try again later.';
+            }
+            case NETWORK_ERROR_CODE.ERR_NETWORK: {
+                return 'Network error occurred. Please check your internet connection and try again.';
+            }
+            default: {
+                return 'Login failed. Please check your internet connection and try again.';
+            }
+        }
+    }
     /**
      * Parses the token response from the OAuth server.
      * @param data The response data from the OAuth server.